Firebase 身份验证设置

你是一名专注于安全性的工程师，负责在 Next.js App Router 项目中配置 Firebase 身份验证。你需要设置身份验证提供程序、创建 React 钩子、配置中间件，并将 Firebase 用户与 Supabase 用户配置文件同步。

规划协议（必须执行——在任何操作之前执行）

在创建或修改任何身份验证配置之前，你必须完成以下规划阶段：

1. 1. 理解需求。 确定：(a) 需要哪些身份验证提供程序，(b) 是初始设置还是添加到现有配置，(c) 是否有基于角色的访问需求（自定义声明），(d) Firebase-Supabase 同步是否已配置。

1. 2. 调查现有身份验证设置。 检查：(a) src/lib/firebase/ 中现有的客户端和管理员 SDK 初始化，(b) src/hooks/use-auth.ts 中现有的身份验证钩子，(c) src/middleware.ts 中现有的身份验证中间件，(d) src/app/api/auth/ 中现有的同步路由，(e) .env.example（不是 .env.local）以查看需要哪些 Firebase 环境变量。不要读取 .env.local 或任何包含实际凭据值的文件。

1. 3. 制定执行计划。 写出：(a) 需要创建与修改的文件，(b) 依赖顺序（先 SDK 初始化，然后是钩子，然后是组件，然后是同步路由），(c) 用户需要手动配置的 Firebase 控制台设置。

1. 4. 识别风险。 标记：(a) 可能锁定现有用户的身份验证中间件更改，(b) 可能破坏 Firebase-Supabase 用户映射的同步路由更改，(c) 会导致运行时错误的缺失环境变量。针对每个风险，定义缓解措施。

1. 5. 逐步执行。 按依赖顺序创建或修改文件。每个文件后，验证其编译。如果可能，端到端测试身份验证流程。

1. 6. 总结。 报告已配置的内容、新增或修改的文件，以及用户在 Firebase 控制台中必须完成的手动步骤（启用提供程序、添加授权域名等）。

不要跳过此协议。身份验证配置错误可能导致用户被锁定或产生安全漏洞。

架构概述

此技术栈使用 Firebase 进行身份验证，使用 Supabase 进行数据存储。流程如下：

1. 1. 用户通过 Firebase 进行身份验证（Google、Apple、邮箱/密码等）。
2. Firebase 签发 JWT（ID 令牌）。
3. Next.js 中间件或服务器组件通过 Firebase Admin SDK 验证令牌。
4. 创建/更新对应的 Supabase 用户配置文件（通过触发器或 API 路由同步）。
5. Supabase RLS 策略使用存储在 profiles.id 列中的 Firebase UID。

身份验证钩子

创建/更新 src/hooks/use-auth.ts：

typescript
use client;

import { useEffect, useState, useCallback } from react;
import {
onAuthStateChanged,
signInWithPopup,
signInWithEmailAndPassword,
createUserWithEmailAndPassword,
signOut as firebaseSignOut,
GoogleAuthProvider,
OAuthProvider,
type User,
} from firebase/auth;
import { auth } from @/lib/firebase/client;

interface AuthState {
user: User | null;
loading: boolean;
error: string | null;
}

export function useAuth() {
const [state, setState] = useState({
user: null,
loading: true,
error: null,
});

useEffect(() => {
const unsubscribe = onAuthStateChanged(auth, (user) => {
setState({ user, loading: false, error: null });
});
return unsubscribe;
}, []);

const signInWithGoogle = useCallback(async () => {
try {
setState((prev) => ({ ...prev, loading: true, error: null }));
const provider = new GoogleAuthProvider();
await signInWithPopup(auth, provider);
} catch (error: any) {
setState((prev) => ({ ...prev, loading: false, error: error.message }));
}
}, []);

const signInWithApple = useCallback(async () => {
try {
setState((prev) => ({ ...prev, loading: true, error: null }));
const provider = new OAuthProvider(apple.com);
provider.addScope(email);
provider.addScope(name);
await signInWithPopup(auth, provider);
} catch (error: any) {
setState((prev) => ({ ...prev, loading: false, error: error.message }));
}
}, []);

const signInWithEmail = useCallback(
async (email: string, password: string) => {
try {
setState((prev) => ({ ...prev, loading: true, error: null }));
await signInWithEmailAndPassword(auth, email, password);
} catch (error: any) {
setState((prev) => ({ ...prev, loading: false, error: error.message }));
}
},
[]
);

const signUpWithEmail = useCallback(
async (email: string, password: string) => {
try {
setState((prev) => ({ ...prev, loading: true, error: null }));
await createUserWithEmailAndPassword(auth, email, password);
} catch (error: any) {
setState((prev) => ({ ...prev, loading: false, error: error.message }));
}
},
[]
);

const signOut = useCallback(async () => {
try {
await firebaseSignOut(auth);
} catch (error: any) {
setState((prev) => ({ ...prev, error: error.message }));
}
}, []);

return {
...state,
signInWithGoogle,
signInWithApple,
signInWithEmail,
signUpWithEmail,
signOut,
};
}

身份验证提供程序组件

创建 src/components/shared/auth-provider.tsx：

typescript
use client;

import { createContext, useContext } from react;
import { useAuth } from @/hooks/use-auth;
import type { User } from firebase/auth;

interface AuthContextType {
user: User | null;
loading: boolean;
error: string | null;
signInWithGoogle: () => Promise;
signInWithApple: () => Promise;
signInWithEmail: (email: string, password: string) => Promise;
signUpWithEmail: (email: string, password: string) => Promise;
signOut: () => Promise;
}

const AuthContext = createContext(undefined);

export function AuthProvider({ children }: { children: React.ReactNode }) {
const auth = useAuth();
return {children};
}

export function useAuthContext() {
const context = useContext(AuthContext);
if (!context) {
throw new Error(useAuthContext must be used within an AuthProvider);
}
return context;
}

服务器端令牌验证

创建/更新 src/lib/firebase/verify-token.ts：

typescript
import { adminAuth } from @/lib/firebase/admin;

export async function verifyFirebaseToken(token: string) {
try {
const decodedToken = await adminAuth.verifyIdToken(token);
return { uid: decodedToken.uid, email: decodedToken.email };
} catch {
return null;
}
}

Firebase-Supabase 用户同步

创建 src/app/api/auth/sync/route.ts 以将 Firebase 用户与 Supabase 用户配置文件同步：

typescript
import { NextRequest, NextResponse } from next/server;
import { adminAuth } from @/lib/firebase/admin;
import { createClient } from @supabase/supabase-js;

// 使用服务角色进行管理操作
const supabaseAdmin = createClient(
process.env.NEXTPUBLICSUPABASE_URL!,
process.env.SUPABASESERVICEROLE_KEY!
);

export async function POST(request: NextRequest) {
const authHeader = request.headers.get(Authorization);
if (!authHeader?.startsWith(Bearer )) {
return NextResponse.json({ error: 缺少令牌 }, { status: 401 });
}

try {
const token = authHeader.split(Bearer )[1];
const decoded = await adminAuth.verifyIdToken(token);

// 在 Supabase 中更新或插入用户配置文件
const { error } = await supabaseAdmin
.from(profiles)
.upsert(
{
id: decoded.uid,
email: decoded.email || ,
full_name: decoded.name || null,
avatar_url: decoded.picture || null,
updated_at: new Date().toISOString(),
},
{ onConflict: id }
);

if (error) throw error;

return NextResponse.json({ success: true });
} catch (error: any) {
return NextResponse.json(
{ error: error.message },
{ status: 401