auth

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Auth Configuration

身份验证配置

1. The Specialized Auth Bounded Context

1. 专用的Auth限界上下文

The auth Bounded Context is a specialized module. Unlike standard 4-layer DDD modules, it acts strictly as an infrastructural bridge wrapping the Better Auth library. You MUST adhere to the following file responsibilities:

Server Configuration (
auth.ts
): The single source of truth for the Server Configuration (adapters, plugins, session logic).
Client Configuration (
auth-client.ts
): The Client Configuration. Exports
```
createAuthClient
```
for use in
```
"use client"
```
components to invoke sign-in flows (e.g.,
```
signIn.magicLink
```
).
Session Wrapper (
getSession.ts
): A wrapper utility that bridges the session to Domain Use Cases, preventing direct dependencies on Next.js headers inside the Domain.
UI Components: UI components exclusive to authentication (Login views, magic link forms).
Email Templates: React Email templates used for outbound transactional emails.

Auth限界上下文是一个专用模块。与标准的四层DDD模块不同，它严格作为封装Better Auth库的基础设施桥梁存在。你必须遵守以下文件职责划分：

服务端配置（
auth.ts
）：服务端配置的唯一可信来源（包含适配器、插件、会话逻辑）。
客户端配置（
auth-client.ts
）：客户端配置文件。导出
```
createAuthClient
```
供
```
"use client"
```
组件调用登录流程（例如
```
signIn.magicLink
```
）。
会话包装器（
getSession.ts
）：将会话与领域用例桥接的工具类，避免领域层直接依赖Next.js请求头。
UI组件：专用于身份验证的UI组件（登录视图、魔法链接表单）。
邮件模板：用于发送事务性邮件的React Email模板。

2. Server Configuration Rules (

auth.ts

)

2. 服务端配置规则（

auth.ts

）

When modifying

auth.ts

, you MUST follow these constraints:

Drizzle Adapter: The
```
drizzleAdapter
```
MUST be used. It MUST map to the PostgreSQL schema via
```
src/shared/infrastructure/postgres/schema.ts
```
(or
```
drizzle-postgres/
```
as configured).

UUID Generation: Because this project enforces strict Domain-Driven Design (DDD) using UUIDv7 as identity primitives, you MUST override the default random string generation in Better Auth.

typescript

advanced: {
  generateId: false, // Let Postgres/Drizzle default generate the UUIDv7
}
// or if strictly handled within the library:
advanced: {
  database: {
    generateId: "uuid", // Assuming standard UUID mapping
  }
}

Environment Variables: All secret keys (e.g.,
```
GOOGLE_CLIENT_ID
```
,
```
RESEND_API_KEY
```
) MUST be imported directly from
```
src/shared/infrastructure/load-env.ts
```
. You MUST NOT use
```
process.env
```
.
Plugins: For passwordless entry, use the
```
magicLink
```
and
```
emailOTP
```
plugins.

修改

auth.ts

时，必须遵循以下约束：

Drizzle适配器：必须使用
```
drizzleAdapter
```
，且必须通过
```
src/shared/infrastructure/postgres/schema.ts
```
（或配置好的
```
drizzle-postgres/
```
）映射到PostgreSQL schema。

UUID生成：由于本项目采用严格的领域驱动设计（DDD），以UUIDv7作为身份原语，你必须覆盖Better Auth中的默认随机字符串生成逻辑。

typescript

advanced: {
  generateId: false, // 让Postgres/Drizzle默认生成UUIDv7
}
// 或者如果严格在库内处理：
advanced: {
  database: {
    generateId: "uuid", // 假设使用标准UUID映射
  }
}

环境变量：所有密钥（如

GOOGLE_CLIENT_ID

、

RESEND_API_KEY

）必须直接从

src/shared/infrastructure/load-env.ts

导入，禁止使用

process.env

。

插件：无密码登录需使用
```
magicLink
```
和
```
emailOTP
```
插件。

3. Email Infrastructure (Resend &

react-email

)

3. 邮件基础设施（Resend &

react-email

）

You MUST NOT use the library's default basic email sender logic.

Both
```
magicLink
```
and
```
emailOTP
```
plugins MUST be configured to use Resend.
The
```
resend
```
instance MUST be imported from the centralized service container.
The email HTML bodies MUST be generated using React components. You MUST NOT write raw HTML string templates inside
```
auth.ts
```
.
Dependencies: You MUST use the
```
@react-email/components
```
library (which includes components like
```
<Html>
```
,
```
<Head>
```
,
```
<Button>
```
) to build these templates safely. The templates are rendered to static markup before being sent via Resend.

禁止使用库自带的基础邮件发送逻辑。

```
magicLink
```
和
```
emailOTP
```
插件必须配置为使用Resend。
```
resend
```
实例必须从中心化服务容器导入。
邮件HTML内容必须使用React组件生成，禁止在
```
auth.ts
```
中编写原始HTML字符串模板。
依赖要求：必须使用
```
@react-email/components
```
库（包含
```
<Html>
```
、
```
<Head>
```
、
```
<Button>
```
等组件）安全构建这些模板。模板会先渲染为静态标记，再通过Resend发送。

4. OAuth Providers (Google Login)

4. OAuth提供商（Google登录）

When setting up Google authentication or other social providers:

You MUST fetch and read the official documentation at
```
https://better-auth.com/docs/authentication/google
```
to understand the setup process.
You MUST provide the user with clear, step-by-step instructions on how to configure the Google Cloud Console (OAuth consent screen, Authorized JavaScript origins, and Redirect URIs).
You MUST ask the user to obtain the
```
GOOGLE_CLIENT_ID
```
and
```
GOOGLE_CLIENT_SECRET
```
and add them to their
```
.env
```
file, ensuring they are also strictly managed via
```
src/shared/infrastructure/load-env.ts
```
.

配置Google身份验证或其他社交提供商时：

必须查阅官方文档

https://better-auth.com/docs/authentication/google

了解配置流程。

必须为用户提供清晰的分步说明，指导其配置Google Cloud Console（OAuth consent screen、授权JavaScript源、重定向URI）。
必须要求用户获取
```
GOOGLE_CLIENT_ID
```
和
```
GOOGLE_CLIENT_SECRET
```
并添加到
```
.env
```
文件，同时确保这些变量通过
```
src/shared/infrastructure/load-env.ts
```
严格管理。

5. Retrieving Auth State in Next.js

5. 在Next.js中获取身份验证状态

In Server Actions

在服务端动作（Server Actions）中

You MUST protect Server Actions. Obtaining the user session MUST be the very first operation inside the action.

typescript

import { auth } from "@/auth/auth";
import { headers } from "next/headers";

// Inside the server action
const session = await auth.api.getSession({ headers: await headers() });
if (!session) {
  return { success: false, error: "UNAUTHORIZED" };
}

必须保护服务端动作，获取用户会话必须是动作内的第一个操作。

typescript

import { auth } from "@/auth/auth";
import { headers } from "next/headers";

// 在服务端动作内部
const session = await auth.api.getSession({ headers: await headers() });
if (!session) {
  return { success: false, error: "UNAUTHORIZED" };
}

In Server Components

在服务端组件（Server Components）中

Server Components can fetch the session the same way to dictate layout logic or pass user data down the tree.

typescript

import { auth } from "@/auth/auth";
import { headers } from "next/headers";

const session = await auth.api.getSession({ headers: await headers() });

服务端组件可通过相同方式获取会话，以控制布局逻辑或向下传递用户数据。

typescript

import { auth } from "@/auth/auth";
import { headers } from "next/headers";

const session = await auth.api.getSession({ headers: await headers() });

In Client Components

在客户端组件（Client Components）中

Client components MUST use hooks generated by

auth-client.ts

(e.g.,

useSession()

) if they need reactive auth state.

如果需要响应式身份验证状态，客户端组件必须使用

auth-client.ts

生成的钩子（例如

useSession()

）。

6. Bridging Auth to Use Cases

6. 身份验证与用例的桥接

Domain Use Cases MUST NOT know about

Better Auth

, HTTP headers, or Next.js. Any Use Case requiring the current user's ID MUST receive it as part of its isolated

Params

payload.

The Server Action acts as the adapter:

Server Action calls
```
auth.api.getSession()
```
.
Extracts
```
session.user.id
```
.

Passes the ID standardly via

serviceContainer.module.useCase.execute({ userId: session.user.id, ...params })

领域用例不得知晓

Better Auth

、HTTP请求头或Next.js相关内容。任何需要当前用户ID的用例，必须将其作为独立

Params

负载的一部分传入。

服务端动作作为适配器：

服务端动作调用
```
auth.api.getSession()
```
。
提取
```
session.user.id
```
。

通过

serviceContainer.module.useCase.execute({ userId: session.user.id, ...params })

标准化传递ID。

7. References

7. 参考资料

For practical examples, you MUST refer to:

Auth Reference: A complete reference showing how the the
```
drizzleAdapter
```
, schemas, Resend integration, and
```
magicLink
```
/
```
emailOTP
```
plugins are combined following these strict rules.

如需实用示例，必须参考：

身份验证参考：完整参考文档，展示如何遵循这些严格规则组合使用
```
drizzleAdapter
```
、schemas、Resend集成以及
```
magicLink
```
/
```
emailOTP
```
插件。

auth

Original

Translation

Auth Configuration

身份验证配置

1. The Specialized Auth Bounded Context

1. 专用的Auth限界上下文

2. Server Configuration Rules (
`auth.ts`
)

2. 服务端配置规则（
`auth.ts`
）

3. Email Infrastructure (Resend &
`react-email`
)

3. 邮件基础设施（Resend &
`react-email`
）

4. OAuth Providers (Google Login)

4. OAuth提供商（Google登录）

5. Retrieving Auth State in Next.js

5. 在Next.js中获取身份验证状态

In Server Actions

在服务端动作（Server Actions）中

In Server Components

在服务端组件（Server Components）中

In Client Components

在客户端组件（Client Components）中

6. Bridging Auth to Use Cases

6. 身份验证与用例的桥接

7. References

7. 参考资料

auth

Original

Translation

Auth Configuration

身份验证配置

1. The Specialized Auth Bounded Context

1. 专用的Auth限界上下文

2. Server Configuration Rules (auth.ts)

2. 服务端配置规则（auth.ts）

3. Email Infrastructure (Resend & react-email)

3. 邮件基础设施（Resend & react-email）

4. OAuth Providers (Google Login)

4. OAuth提供商（Google登录）

5. Retrieving Auth State in Next.js

5. 在Next.js中获取身份验证状态

In Server Actions

在服务端动作（Server Actions）中

In Server Components

在服务端组件（Server Components）中

In Client Components

在客户端组件（Client Components）中

6. Bridging Auth to Use Cases

6. 身份验证与用例的桥接

7. References

7. 参考资料

2. Server Configuration Rules (
`auth.ts`
)

2. 服务端配置规则（
`auth.ts`
）

3. Email Infrastructure (Resend &
`react-email`
)

3. 邮件基础设施（Resend &
`react-email`
）