Client Auth

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>com.example.myapp.auth</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>myapp</string>
    </array>
  </dict>
</array>

import PortalSwift

let portalAuth = try PortalAuth(
    authEnvironmentId: "YOUR_AUTH_ENVIRONMENT_ID",
    redirectUrl: "myapp://auth/callback",
    // Required only by sendMagicLink()
    magicLink: MagicLinkConfig(
        fromEmail: "hello@auth.example.com",
        templateId: "YOUR_TEMPLATE_ID"
    ),
    // Optional: whether the client Portal creates uses gas sponsorship
    isAccountAbstracted: nil
)

import PortalSwift

func loadMethods() async throws -> AuthMethodsResult {
    let methods = try await portalAuth.getMethods()

    print("✅ enabled: \(methods.allowedAuthMethods.map(\.rawValue))") // ["GOOGLE", "EMAIL_MAGIC_LINK"]
    print("✅ autoCreateWallet: \(methods.autoCreateWallet)")

    return methods
}

import PortalSwift
import UIKit

@MainActor
func signIn(with method: AuthMethod, from window: UIWindow) async {
    // Held weakly, so set it again if the window changes.
    portalAuth.setAuthPresentationAnchor(window)

    do {
        let result: AuthResult
        switch method {
        case .google:
            result = try await portalAuth.signInWithGoogle()
        case .apple:
            result = try await portalAuth.signInWithApple()
        case .emailMagicLink:
            return
        }

        switch result {
        case .authenticated(let authenticated):
            onSignedIn(authenticated.session)
        case .totpRequired(let step):
            promptForTotp(step)
        }
    } catch PortalAuthSignInError.closed {
        // The user dismissed the sheet. Nothing to clean up.
    } catch PortalAuthSignInError.signInInProgress {
        // A sign-in is already running. Ignore the extra tap.
    } catch {
        print("❌ Sign-in failed: \(error)")
    }
}

import PortalSwift
import UIKit

@MainActor
func openSignIn(with method: AuthMethod) async {
    do {
        let authorize: AuthorizeUrlResult
        switch method {
        case .google:
            authorize = try await portalAuth.loginWithGoogle()
        case .apple:
            authorize = try await portalAuth.loginWithApple()
        case .emailMagicLink:
            return
        }

        guard let url = URL(string: authorize.authorizeUrl),
              await UIApplication.shared.open(url)
        else {
            print("❌ Could not open the authorize URL.")
            return
        }
        // The result arrives as a redirect. See Complete the sign-in.
    } catch {
        print("❌ Could not start the sign-in: \(error)")
    }
}

import PortalSwift

@MainActor
func sendMagicLink(to input: String) async {
    do {
        // Trimmed and lowercased by the SDK before it is sent.
        try await portalAuth.sendMagicLink(input)

        print("✅ magic link sent")
    } catch PortalAuthError.rateLimited {
        print("❌ Too many links were sent to this address. Wait a minute and try again.")
    } catch {
        print("❌ sendMagicLink failed: \(error)")
    }
}

import Foundation
import PortalSwift

@MainActor
func completeSignIn(with url: URL) async {
    do {
        // Not a Client Auth redirect — let the rest of your routing handle it.
        guard let result = try await portalAuth.handleRedirect(url) else { return }

        switch result {
        case .authenticated(let authenticated):
            // Must be safe to run twice — see the warning below.
            onSignedIn(authenticated.session)
        case .totpRequired(let step):
            promptForTotp(step)
        }
    } catch PortalAuthError.authenticationFailed {
        print("❌ the user did not complete the provider sign-in")
    } catch PortalRequestsError.unauthorized {
        // Already used, expired, or issued for another environment.
        print("❌ this sign-in link is no longer valid — start a new sign-in")
    } catch {
        print("❌ handleRedirect failed: \(error)")
    }
}

import PortalSwift
import UIKit

/// What to show a first-time user. `nil` once the user is enrolled.
func enrollment(for step: TotpRequiredResult) -> (qrCode: UIImage?, manualKey: String?)? {
    guard step.totpLink != nil else { return nil }

    // A QR code for the authenticator app to scan, and the base32 key for users who cannot scan.
    return (try? step.qrCodeImage(), step.totpSecret)
}

import PortalSwift

@MainActor
func verifyTotp(code: String, step: TotpRequiredResult) async {
    do {
        let authenticated = try await portalAuth.verifyTotp(code, userJwt: step.userJwt)

        // The same session the non-TOTP path returns.
        onSignedIn(authenticated.session)
    } catch PortalRequestsError.unauthorized {
        // A rejected code does not consume the userJwt, so prompting again is normal.
        print("❌ verifyTotp failed — ask for the next code")
    } catch PortalAuthError.invalidUserJwt {
        print("❌ this two-factor step can no longer be used — start a new sign-in")
    } catch {
        // A Keychain write that failed after the code was accepted: retry with the
        // same userJwt. A dropped connection: retrying usually works, but if the code
        // was accepted before the connection dropped, start a new sign-in.
        print("❌ verifyTotp failed: \(error)")
    }
}

import PortalSwift

func createPortal(session: PortalSession) throws -> Portal {
    try Portal(
        credentials: session,
        withRpcConfig: [
            "eip155:1": "https://api.portalhq.io/rpc/v1/eip155/1",
            "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp": "https://api.mainnet-beta.solana.com"
        ]
    )
}

import PortalSwift

func resolveWallet(portal: Portal) async throws {
    if try await portal.doesWalletExist() {
        if try await portal.isWalletOnDevice() {
            print("✅ reusing the existing wallet")
        } else {
            // The wallet exists elsewhere — recover it. See Recover a wallet.
            print("✅ wallet exists but is not on this device")
        }
        return
    }

    guard try await portalAuth.getMethods().autoCreateWallet else {
        print("✅ autoCreateWallet is off — not creating a wallet")
        return
    }

    let addresses = try await portal.createWallet()
    print("✅ wallet created: \(addresses.ethereum)")
}

import Foundation
import PortalSwift

func restore() async -> PortalSession? {
    // Keychain items survive app deletion. Start a fresh install from a clean slate.
    let defaults = UserDefaults.standard
    if !defaults.bool(forKey: "portalAuthLaunchedBefore") {
        do {
            try await portalAuth.clearPersistedSession()
            defaults.set(true, forKey: "portalAuthLaunchedBefore")
        } catch {
            // Do not restore: what is stored may belong to the previous install.
            print("❌ could not clear the previous install's session: \(error)")
            return nil
        }
    }

    do {
        guard let session = try await portalAuth.restoreSession() else {
            print("✅ nothing stored — show the sign-in screen")
            return nil
        }
        return session
    } catch {
        // PortalAuthError.sessionStorageFailure: storage failed this time. It may succeed on the next attempt.
        print("❌ restoreSession failed: \(error)")
        return nil
    }
}

import PortalSwift

// Signing the current user out. Run both, even if one fails: each clears
// something the other does not.
func signOut(portal: Portal) async {
    do {
        try await portal.clearSession()
    } catch {
        // The in-memory token is gone either way; a stale copy may remain in the Keychain.
        print("❌ clearSession failed: \(error)")
    }

    do {
        try await portalAuth.clearPersistedSession()
    } catch {
        print("❌ clearPersistedSession failed: \(error)")
    }
}

import Combine
import PortalSwift

@MainActor
final class PortalHolder: ObservableObject {
    static let shared = PortalHolder()

    @Published private(set) var portal: Portal?
    @Published private(set) var sessionEnded = false

    private var subscription: PortalSessionInvalidationHandle?

    private init() {}

    func adopt(_ session: PortalSession) throws {
        // Cancelled first: each Portal needs its own subscription, and a delivery the
        // previous one already queued must not reach the new user.
        subscription?.cancel()

        let created = try createPortal(session: session)
        // Runs once, on the main actor. Capture self weakly: the listener is retained
        // for as long as the session is.
        subscription = created.onSessionInvalidated { [weak self] in
            self?.sessionEnded = true
        }

        portal = created
        sessionEnded = false
    }

    func signedOut() {
        subscription?.cancel()
        subscription = nil
        portal = nil
        sessionEnded = false
    }
}

import PortalSwift

/// - Parameter completingSignIn: `true` when the error came from `handleRedirect(_:)`.
///   A `401` means a spent or expired grant only there; from `signInWith*` it can also
///   be a configuration problem, so it falls through to the generic message.
func describe(_ error: Error, completingSignIn: Bool) -> String {
    switch error {
    case PortalAuthError.authMethodUnavailable:
        return "That sign-in method is not available."
    case PortalAuthError.authenticationFailed, PortalAuthSignInError.closed:
        return "Sign-in was not completed."
    case PortalAuthError.rateLimited:
        return "Too many sign-in links were sent. Please wait a minute and try again."
    case let credentialError as PortalCredentialError:
        return credentialError.requiresReauthentication
            ? "Your session ended. Please sign in again."
            : "Could not read your session. Please try again."
    case PortalRequestsError.unauthorized:
        return completingSignIn
            ? "That sign-in link has expired. Please start a new sign-in."
            : "That request was rejected. Please try again."
    default:
        return "Something went wrong."
    }
}