initial commit: Proximity iOS app proposal, full Swift code scaffold, reference backend, testing docs, generated Xcode project

Proximity/Services/Auth/AuthProvider.swift

@@ -0,0 +1,46 @@
+import Foundation
+
+/// A provider that can authenticate a user and return an identity token
+/// that our backend exchanges for a Proximity session.
+protocol AuthProvider {
+    var providerID: AuthProviderID { get }
+    /// Begin the sign-in flow and return an ID token + raw profile claims.
+    func signIn() async throws -> AuthResult
+    /// Sign out locally.
+    func signOut() async throws
+}
+
+/// Supported authentication providers.
+enum AuthProviderID: String, Codable, CaseIterable {
+    case apple
+    case google
+    // case x   // X (Twitter) OAuth — see note in AuthService
+    // case instagram  // Instagram is NOT an OAuth provider for login
+
+    var displayName: String {
+        switch self {
+        case .apple:  return "Apple"
+        case .google: return "Google"
+        }
+    }
+}
+
+/// The result of a successful provider sign-in.
+struct AuthResult {
+    let providerID: AuthProviderID
+    /// Provider-issued ID token (JWT) — sent to our backend for verification.
+    let idToken: String
+    /// Nonce used to prevent replay (Apple requires it).
+    let nonce: String?
+    /// Raw profile claims the provider returned (name, email, etc.).
+    let profile: ProviderProfile
+}
+
+/// Raw profile claims returned by a provider at sign-in time.
+struct ProviderProfile {
+    var name: String?
+    var email: String?
+    var givenName: String?
+    var familyName: String?
+    var pictureURL: URL?
+}