Never Embed Your Gemini API Key in a Mobile App: Complete Multi-Layer Security Architecture with Firebase App Check

# Install Firebase CLI if needed
npm install -g firebase-tools
firebase login
 
# Initialize Cloud Functions in your project
firebase init functions   # Select TypeScript or JavaScript
 
# Set the Gemini API key as an encrypted secret
firebase functions:secrets:set GEMINI_API_KEY
# You'll be prompted to enter the key value — it's never stored in plaintext

cd functions
npm install @google/generative-ai firebase-admin firebase-functions

// functions/index.js
const { onRequest } = require("firebase-functions/v2/https");
const { initializeApp } = require("firebase-admin/app");
const { getFirestore, FieldValue } = require("firebase-admin/firestore");
const { getAppCheck } = require("firebase-admin/app-check");
const { GoogleGenerativeAI } = require("@google/generative-ai");
const crypto = require("crypto");
 
initializeApp();
const db = getFirestore();
 
// Gemini client — lives only on the server. Never in client code.
const genai = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);
 
// Configurable limits — tune these for your app's use case
const LIMITS = {
  requestsPerMinute: 10,
  requestsPerDay: 100,
  maxPromptChars: 4000,
  maxOutputTokens: 2000,
  anomalyThreshold: 10,    // same prompt N times in...
  anomalyWindowMs: 300_000, // ...5 minutes = anomaly
};
 
/** Validates an App Check token. Returns false if missing or invalid. */
async function verifyAppCheck(token) {
  if (!token) return false;
  try {
    await getAppCheck().verifyToken(token);
    return true;
  } catch (err) {
    console.warn("App Check token invalid:", err.message);
    return false;
  }
}
 
/**
 * Checks and records per-user rate limits using Firestore transactions.
 * Returns { allowed: boolean, reason?: string }.
 */
async function checkRateLimit(userId) {
  const now = Date.now();
  const oneMinuteAgo = now - 60_000;
  const oneDayAgo = now - 86_400_000;
  const ref = db.collection("ratelimits").doc(userId);
 
  return db.runTransaction(async (tx) => {
    const doc = await tx.get(ref);
    // Expire timestamps older than 1 day
    const requests = (doc.exists ? doc.data().requests : []).filter(
      (ts) => ts > oneDayAgo
    );
 
    const lastMinuteCount = requests.filter((ts) => ts > oneMinuteAgo).length;
    if (lastMinuteCount >= LIMITS.requestsPerMinute) {
      return {
        allowed: false,
        reason: `Rate limit: max ${LIMITS.requestsPerMinute} requests per minute`,
      };
    }
    if (requests.length >= LIMITS.requestsPerDay) {
      return {
        allowed: false,
        reason: `Daily limit: max ${LIMITS.requestsPerDay} requests per day`,
      };
    }
 
    requests.push(now);
    tx.set(ref, {
      requests,
      lastRequest: now,
      updatedAt: FieldValue.serverTimestamp(),
    });
 
    return { allowed: true };
  });
}
 
/**
 * Detects anomalous usage: identical prompt repeated too quickly.
 * Returns true if anomalous (request should be blocked).
 */
async function detectAnomaly(userId, promptHash) {
  const key = `${userId}_${promptHash}`;
  const ref = db.collection("anomaly").doc(key);
  const doc = await ref.get();
 
  if (!doc.exists) {
    await ref.set({
      count: 1,
      firstSeen: Date.now(),
      lastSeen: Date.now(),
      blocked: false,
    });
    return false;
  }
 
  const { count = 0, firstSeen, blocked } = doc.data();
  if (blocked) return true; // Already flagged
 
  const newCount = count + 1;
  const withinWindow = Date.now() - firstSeen < LIMITS.anomalyWindowMs;
 
  if (newCount >= LIMITS.anomalyThreshold && withinWindow) {
    await ref.update({ count: newCount, lastSeen: Date.now(), blocked: true });
    console.warn(`Anomaly blocked: userId=${userId}, promptHash=${promptHash}`);
    return true;
  }
 
  await ref.update({ count: newCount, lastSeen: Date.now() });
  return false;
}
 
/** The main proxy endpoint. */
exports.geminiProxy = onRequest(
  {
    region: "asia-northeast1",   // Tokyo — change to your preferred region
    memory: "256MiB",
    timeoutSeconds: 30,
    secrets: ["GEMINI_API_KEY"],
  },
  async (req, res) => {
    // CORS headers — tighten origin in production if calling from a web app too
    res.set("Access-Control-Allow-Origin", "*");
    if (req.method === "OPTIONS") {
      res.set("Access-Control-Allow-Methods", "POST");
      res.set("Access-Control-Allow-Headers", "Content-Type, X-Firebase-AppCheck");
      return res.status(204).send("");
    }
    if (req.method !== "POST") {
      return res.status(405).json({ error: "Method not allowed" });
    }
 
    try {
      // --- Layer 1: App Check verification ---
      const appCheckToken = req.headers["x-firebase-appcheck"];
      if (!(await verifyAppCheck(appCheckToken))) {
        return res.status(403).json({
          error: "unauthorized",
          message: "Device verification failed.",
        });
      }
 
      // --- Input validation ---
      const { prompt, userId, model = "gemini-2.5-flash" } = req.body;
      if (!prompt || typeof prompt !== "string") {
        return res.status(400).json({ error: "prompt (string) is required" });
      }
      if (!userId || typeof userId !== "string") {
        return res.status(400).json({ error: "userId (string) is required" });
      }
      if (prompt.length > LIMITS.maxPromptChars) {
        return res.status(400).json({
          error: "prompt_too_long",
          message: `Prompt must be under ${LIMITS.maxPromptChars} characters`,
        });
      }
 
      // Allowlist model names to prevent injecting arbitrary model IDs
      const allowedModels = ["gemini-2.5-flash", "gemini-2.5-pro", "gemini-2.5-flash-lite"];
      if (!allowedModels.includes(model)) {
        return res.status(400).json({ error: "invalid_model" });
      }
 
      // --- Layer 2: Rate limiting ---
      const { allowed, reason } = await checkRateLimit(userId);
      if (!allowed) {
        return res.status(429).json({ error: "rate_limit_exceeded", message: reason });
      }
 
      // --- Layer 3: Anomaly detection ---
      const promptHash = crypto.createHash("md5").update(prompt).digest("hex");
      if (await detectAnomaly(userId, promptHash)) {
        return res.status(429).json({
          error: "anomaly_detected",
          message: "Unusual request pattern detected. Please try again later.",
        });
      }
 
      // --- Call Gemini API (API key never leaves this function) ---
      const geminiModel = genai.getGenerativeModel({
        model,
        generationConfig: {
          maxOutputTokens: LIMITS.maxOutputTokens,
          temperature: 0.7,
        },
        safetySettings: [
          // Adjust based on your app's content policy
          { category: "HARM_CATEGORY_HARASSMENT", threshold: "BLOCK_MEDIUM_AND_ABOVE" },
          { category: "HARM_CATEGORY_HATE_SPEECH", threshold: "BLOCK_MEDIUM_AND_ABOVE" },
        ],
      });
 
      const result = await geminiModel.generateContent(prompt);
      const text = result.response.text();
      const usage = result.response.usageMetadata ?? {};
 
      // --- Log usage for cost tracking ---
      await db.collection("usage_logs").add({
        userId,
        model,
        promptLength: prompt.length,
        inputTokens: usage.promptTokenCount ?? 0,
        outputTokens: usage.candidatesTokenCount ?? 0,
        timestamp: FieldValue.serverTimestamp(),
      });
 
      return res.status(200).json({ text });
    } catch (err) {
      console.error("Proxy error:", err);
      // Don't expose internal error details to clients
      return res.status(500).json({ error: "internal_error" });
    }
  }
);

firebase deploy --only functions:geminiProxy

// GeminiAppDelegate.swift
import SwiftUI
import FirebaseCore
import FirebaseAppCheck
 
@main
struct MyApp: App {
    init() {
        FirebaseApp.configure()
        configureAppCheck()
    }
 
    private func configureAppCheck() {
        // App Attest in production, DebugProvider in simulator or CI
        #if targetEnvironment(simulator)
        let providerFactory = AppCheckDebugProviderFactory()
        #elseif DEBUG
        // Real device debug builds: use DebugProvider with a registered debug token
        let providerFactory = AppCheckDebugProviderFactory()
        #else
        // Production: use App Attest (iOS 14+) with DeviceCheck as fallback
        if #available(iOS 14.0, *) {
            let providerFactory = AppAttestProviderFactory()
            AppCheck.setAppCheckProviderFactory(providerFactory)
            return
        }
        let providerFactory = DeviceCheckProviderFactory()
        #endif
        AppCheck.setAppCheckProviderFactory(providerFactory)
    }
 
    var body: some Scene {
        WindowGroup { ContentView() }
    }
}
 
// GeminiService.swift
// No API key in this file — only the Cloud Functions URL
@MainActor
class GeminiService: ObservableObject {
    // Store this in a config plist or environment, not hardcoded in source
    private let functionURL =
        "https://asia-northeast1-YOUR_PROJECT_ID.cloudfunctions.net/geminiProxy"
 
    @Published var isLoading = false
    @Published var lastError: String?
 
    func generate(prompt: String, userId: String) async -> String? {
        isLoading = true
        lastError = nil
        defer { isLoading = false }
 
        do {
            return try await callBackend(prompt: prompt, userId: userId)
        } catch GeminiClientError.rateLimited {
            lastError = "You've hit the request limit. Please wait before trying again."
        } catch GeminiClientError.unauthorized {
            lastError = "Device verification failed. Make sure you're using the official app."
        } catch {
            lastError = "Something went wrong. Please try again."
        }
        return nil
    }
 
    private func callBackend(prompt: String, userId: String, retried: Bool = false) async throws -> String {
        // Fetch App Check token — SDK caches it and refreshes automatically
        let tokenResult = try await AppCheck.appCheck().token(forcingRefresh: false)
 
        guard let url = URL(string: functionURL) else { throw GeminiClientError.configError }
 
        var request = URLRequest(url: url)
        request.httpMethod = "POST"
        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
        request.setValue(tokenResult.token, forHTTPHeaderField: "X-Firebase-AppCheck")
        request.timeoutInterval = 30
 
        let body = ["prompt": prompt, "userId": userId, "model": "gemini-2.5-flash"]
        request.httpBody = try JSONSerialization.data(withJSONObject: body)
 
        let (data, response) = try await URLSession.shared.data(for: request)
        guard let http = response as? HTTPURLResponse else { throw GeminiClientError.networkError }
 
        switch http.statusCode {
        case 200:
            let decoded = try JSONDecoder().decode(GeminiResponse.self, from: data)
            return decoded.text
        case 403 where !retried:
            // Token may have expired mid-session — retry once with force-refresh
            _ = try await AppCheck.appCheck().token(forcingRefresh: true)
            return try await callBackend(prompt: prompt, userId: userId, retried: true)
        case 403:
            throw GeminiClientError.unauthorized
        case 429:
            throw GeminiClientError.rateLimited
        default:
            throw GeminiClientError.serverError(http.statusCode)
        }
    }
}
 
enum GeminiClientError: LocalizedError {
    case unauthorized, rateLimited, configError, networkError, serverError(Int)
    var errorDescription: String? {
        switch self {
        case .unauthorized: return "Device verification failed"
        case .rateLimited: return "Request limit reached"
        case .serverError(let c): return "Server error (\(c))"
        default: return "Network error"
        }
    }
}
 
struct GeminiResponse: Codable { let text: String }

implementation(platform("com.google.firebase:firebase-bom:33.x.x"))
implementation("com.google.firebase:firebase-appcheck-playintegrity")
implementation("com.google.firebase:firebase-appcheck-debug")  // debug builds only
implementation("com.squareup.okhttp3:okhttp:4.12.0")

// MyApplication.kt — configure App Check at startup
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        FirebaseApp.initializeApp(this)
 
        val appCheck = FirebaseAppCheck.getInstance()
        if (BuildConfig.DEBUG) {
            // Use debug provider in debug builds (prints token to Logcat)
            appCheck.installAppCheckProviderFactory(
                FirebaseAppCheckDebugProviderFactory.getInstance()
            )
        } else {
            // Use Play Integrity in production builds
            appCheck.installAppCheckProviderFactory(
                PlayIntegrityAppCheckProviderFactory.getInstance()
            )
        }
    }
}
 
// GeminiRepository.kt
class GeminiRepository {
    private val backendUrl =
        "https://asia-northeast1-YOUR_PROJECT_ID.cloudfunctions.net/geminiProxy"
 
    private val json = "application/json; charset=utf-8".toMediaType()
    private val httpClient = OkHttpClient.Builder()
        .connectTimeout(30, TimeUnit.SECONDS)
        .readTimeout(30, TimeUnit.SECONDS)
        .build()
 
    /** Call the backend. Returns Result with the generated text, or an error. */
    suspend fun generate(
        prompt: String,
        userId: String,
        model: String = "gemini-2.5-flash",
        retried: Boolean = false
    ): Result<String> = withContext(Dispatchers.IO) {
        try {
            // Get App Check token (SDK handles caching and refresh)
            val appCheckToken = getAppCheckToken()
                ?: return@withContext Result.failure(SecurityException("Failed to get App Check token"))
 
            val requestBody = JSONObject().apply {
                put("prompt", prompt)
                put("userId", userId)
                put("model", model)
            }.toString().toRequestBody(json)
 
            val request = Request.Builder()
                .url(backendUrl)
                .post(requestBody)
                .addHeader("X-Firebase-AppCheck", appCheckToken)
                .build()
 
            val response = httpClient.newCall(request).execute()
            val responseBody = response.body?.string()
 
            when (response.code) {
                200 -> {
                    val text = JSONObject(responseBody ?: "").getString("text")
                    Result.success(text)
                }
                403 -> {
                    if (!retried) {
                        // Force-refresh token once and retry
                        val freshToken = getAppCheckToken(forceRefresh = true)
                        if (freshToken != null) {
                            return@withContext generate(prompt, userId, model, retried = true)
                        }
                    }
                    Result.failure(SecurityException("Unauthorized"))
                }
                429 -> Result.failure(RateLimitException("Rate limit exceeded"))
                else -> Result.failure(IOException("Server error: ${response.code}"))
            }
        } catch (e: Exception) {
            Result.failure(e)
        }
    }
 
    private suspend fun getAppCheckToken(forceRefresh: Boolean = false): String? =
        suspendCancellableCoroutine { cont ->
            FirebaseAppCheck.getInstance()
                .getAppCheckToken(forceRefresh)
                .addOnSuccessListener { token -> cont.resume(token.token) }
                .addOnFailureListener { err ->
                    Log.e("GeminiRepo", "App Check token failed: ${err.message}")
                    cont.resume(null)
                }
        }
}
 
class RateLimitException(message: String) : Exception(message)

cd functions
npm install --save-dev @firebase/functions-test
 
# Set a fake GEMINI_API_KEY for local testing
export GEMINI_API_KEY="test-key-not-real"
 
# Start Functions emulator
firebase emulators:start --only functions,firestore

// functions/test/geminiProxy.test.js
const test = require("firebase-functions-test")();
 
describe("geminiProxy", () => {
  it("rejects requests without App Check token", async () => {
    const req = { method: "POST", headers: {}, body: { prompt: "hello", userId: "user1" } };
    const res = { status: jest.fn().mockReturnThis(), json: jest.fn(), set: jest.fn() };
    
    await geminiProxy(req, res);
    expect(res.status).toHaveBeenCalledWith(403);
  });
 
  it("rejects oversized prompts", async () => {
    const longPrompt = "a".repeat(5000);
    const req = {
      method: "POST",
      headers: { "x-firebase-appcheck": "valid-debug-token" },
      body: { prompt: longPrompt, userId: "user1" }
    };
    const res = { status: jest.fn().mockReturnThis(), json: jest.fn(), set: jest.fn() };
 
    // Mock verifyAppCheck to return true in tests
    await geminiProxy(req, res);
    expect(res.status).toHaveBeenCalledWith(400);
  });
});

// scripts/weekly-cost-report.js — run via Cloud Scheduler or locally
const admin = require("firebase-admin");
admin.initializeApp();
const db = admin.firestore();
 
// Gemini API pricing as of May 2026 (per 1M tokens)
const PRICE = {
  "gemini-2.5-flash": { input: 0.15, output: 0.60 },
  "gemini-2.5-pro":   { input: 1.25, output: 10.00 },
  "gemini-2.5-flash-lite": { input: 0.075, output: 0.30 },
};
 
async function weeklyReport() {
  const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
  const snapshot = await db
    .collection("usage_logs")
    .where("timestamp", ">=", sevenDaysAgo)
    .get();
 
  const summary = {};
  snapshot.forEach((doc) => {
    const { userId, model, inputTokens = 0, outputTokens = 0 } = doc.data();
    if (!summary[userId]) summary[userId] = { requests: 0, costUsd: 0 };
    summary[userId].requests++;
 
    const pricing = PRICE[model] ?? { input: 0, output: 0 };
    summary[userId].costUsd +=
      (inputTokens / 1_000_000) * pricing.input +
      (outputTokens / 1_000_000) * pricing.output;
  });
 
  console.log("=== Weekly Usage Report ===");
  Object.entries(summary)
    .sort(([, a], [, b]) => b.costUsd - a.costUsd)
    .forEach(([userId, { requests, costUsd }]) => {
      console.log(
        `User ${userId.slice(0, 8)}...: ${requests} requests, $${costUsd.toFixed(4)}`
      );
    });
 
  const total = Object.values(summary).reduce((sum, u) => sum + u.costUsd, 0);
  console.log(`\nTotal: $${total.toFixed(4)}`);
}
 
weeklyReport().then(() => process.exit(0));

// CertificatePinningDelegate.swift
import Foundation
import CryptoKit
 
class PinnedSessionDelegate: NSObject, URLSessionDelegate {
    // SHA-256 hash of your server's public key (get from: openssl s_client -connect
    //   asia-northeast1-YOUR_PROJECT.cloudfunctions.net:443 | openssl x509 -pubkey -noout |
    //   openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | base64)
    private let pinnedKeyHash = "YOUR_BASE64_SHA256_PUBLIC_KEY_HASH"
 
    func urlSession(
        _ session: URLSession,
        didReceive challenge: URLAuthenticationChallenge,
        completionHandler: @escaping (URLSession.AuthChallengeDisposition, URLCredential?) -> Void
    ) {
        guard
            challenge.protectionSpace.authenticationMethod == NSURLAuthenticationMethodServerTrust,
            let serverTrust = challenge.protectionSpace.serverTrust,
            let serverCert = SecTrustGetCertificateAtIndex(serverTrust, 0),
            let publicKey = SecCertificateCopyKey(serverCert),
            let publicKeyData = SecKeyCopyExternalRepresentation(publicKey, nil) as Data?
        else {
            completionHandler(.cancelAuthenticationChallenge, nil)
            return
        }
 
        let hash = SHA256.hash(data: publicKeyData)
        let hashBase64 = Data(hash).base64EncodedString()
 
        if hashBase64 == pinnedKeyHash {
            completionHandler(.useCredential, URLCredential(trust: serverTrust))
        } else {
            completionHandler(.cancelAuthenticationChallenge, nil)
        }
    }
}
 
// Usage in GeminiService:
// let session = URLSession(configuration: .default, delegate: PinnedSessionDelegate(), delegateQueue: nil)
// let (data, response) = try await session.data(for: request)

// Deploy to multiple regions simultaneously
exports.geminiProxyUS = onRequest(
  { region: "us-central1", secrets: ["GEMINI_API_KEY"], ...otherConfig },
  handler
);
 
exports.geminiProxyEU = onRequest(
  { region: "europe-west1", secrets: ["GEMINI_API_KEY"], ...otherConfig },
  handler
);
 
exports.geminiProxyAsia = onRequest(
  { region: "asia-northeast1", secrets: ["GEMINI_API_KEY"], ...otherConfig },
  handler
);

// Endpoint selection by locale (simplified)
func backendURL() -> String {
    let languageCode = Locale.current.language.languageCode?.identifier ?? "en"
    let regionCode = Locale.current.region?.identifier ?? ""
    
    if ["ja", "ko", "zh"].contains(languageCode) || ["JP", "KR", "CN", "TW"].contains(regionCode) {
        return "https://asia-northeast1-YOUR_PROJECT.cloudfunctions.net/geminiProxyAsia"
    } else if Locale.current.region?.identifier.hasPrefix("US") == true {
        return "https://us-central1-YOUR_PROJECT.cloudfunctions.net/geminiProxyUS"
    } else {
        return "https://europe-west1-YOUR_PROJECT.cloudfunctions.net/geminiProxyEU"
    }
}

# iOS project
grep -r "AIza" . --include="*.swift" --include="*.plist" --include="*.xcconfig"
 
# Android project  
grep -r "AIza" . --include="*.kt" --include="*.xml" --include="*.properties" --include="*.json"