@nexttylabs/echo 0.2.0

package/docs/user-story-tracking.md

@@ -0,0 +1,191 @@
+# Echo 用户故事追踪清单（按用户旅程串联）
+
+> 生成日期：2026-01-09
+> 说明：基于 PRD 的用户旅程与现有实现梳理。缺失表示当前未发现对应页面/功能实现。
+
+---
+
+## 旅程 1：Sarah（终端用户）— 让她的声音被听见
+
+**旅程摘要**：用户在产品内提交反馈、上传截图、获取跟踪链接、收到状态通知，并在问题解决后获得正向回馈。
+
+| ID | 用户故事 | 旅程步骤 | 期望能力 | 当前实现 | 对应页面/组件 | 状态 |
+|---|---|---|---|---|---|---|
+| J1-US1 | 作为终端用户，我希望在产品中提交反馈，以便让团队知道我的问题/需求 | 提交反馈 | 嵌入式反馈表单（标题、描述、类型、优先级） | ✅ | `app/widget/[organizationId]/page.tsx` | 已实现 |
+| J1-US2 | 作为终端用户，我希望上传截图/附件，以便说明问题 | 提交反馈 | 附件上传 | ⚠ | 组件存在：`components/feedback/embedded-feedback-form.tsx`，但未挂接到路由 | 部分缺失 |
+| J1-US3 | 作为终端用户，我希望获得反馈跟踪链接，以便随时查看进展 | 提交后 | 跟踪链接/详情页 | ✅ | `app/feedback/[id]/page.tsx` | 已实现 |
+| J1-US4 | 作为终端用户，我希望收到状态变更通知，以便知道处理进度 | 处理阶段 | 邮件/通知 | ❌ | 仅有通知设置页 `app/(dashboard)/settings/notifications/page.tsx` | 缺失 |
+| J1-US5 | 作为终端用户，我希望为其他人的反馈投票，以便表达支持 | 处理中 | 投票 | ⚠ | 后台列表有投票：`app/(dashboard)/feedback/page.tsx`；缺少公开反馈列表页 | 部分缺失 |
+| J1-US6 | 作为终端用户，我希望在问题修复后得到感谢/反馈，以便感受到被重视 | 完成后 | 感谢机制 | ❌ | 未发现页面/功能 | 缺失 |
+
+---
+
+## 旅程 2：Alex（产品经理）— 基于真实需求做决策
+
+**旅程摘要**：产品经理查看仪表盘与反馈列表，按投票/类型/状态筛选，进入详情评估收入影响，并将需求加入路线图、导出报告。
+
+| ID | 用户故事 | 旅程步骤 | 期望能力 | 当前实现 | 对应页面/组件 | 状态 |
+|---|---|---|---|---|---|---|
+| J2-US1 | 作为产品经理，我希望看到反馈统计仪表盘，以便快速了解反馈概况 | 打开后台 | 仪表盘 | ✅ | `app/(dashboard)/dashboard/page.tsx` | 已实现 |
+| J2-US2 | 作为产品经理，我希望按投票/类型/状态筛选反馈，以便聚焦高优先级需求 | 管理反馈 | 筛选/排序 | ✅ | `app/(dashboard)/feedback/page.tsx` | 已实现 |
+| J2-US3 | 作为产品经理，我希望查看反馈详情（投票、附件、状态），以便做决策 | 管理反馈 | 反馈详情 | ✅ | `app/admin/feedback/[id]/page.tsx` | 已实现 |
+| J2-US4 | 作为产品经理，我希望将反馈加入路线图，以便安排版本规划 | 规划 | 路线图/泳道 | ❌ | 未发现页面/功能 | 缺失 |
+| J2-US5 | 作为产品经理，我希望导出报告，以便在会议中展示 | 复盘/汇报 | 报告导出 | ❌ | 未发现页面/功能 | 缺失 |
+| J2-US6 | 作为产品经理，我希望看到收入影响数据，以便做更合理的优先级决策 | 评估 | CRM/收入影响 | ❌ | 未发现页面/功能 | 缺失 |
+
+---
+
+## 旅程 3：Kevin（开发者）— 理解用户真实场景
+
+**旅程摘要**：开发者从反馈详情了解背景、查看附件/评论/内部备注，并将需求同步到项目管理工具。
+
+| ID | 用户故事 | 旅程步骤 | 期望能力 | 当前实现 | 对应页面/组件 | 状态 |
+|---|---|---|---|---|---|---|
+| J3-US1 | 作为开发者，我希望查看反馈详情与附件，以便理解真实场景 | 查看需求 | 反馈详情 + 附件 | ✅ | `app/admin/feedback/[id]/page.tsx` | 已实现 |
+| J3-US2 | 作为开发者，我希望看到产品经理的内部备注，以便理解技术要求 | 协作 | 内部备注 | ✅ | `app/admin/feedback/[id]/page.tsx`（InternalNotes） | 已实现 |
+| J3-US3 | 作为开发者，我希望在反馈页与用户互动评论，以便澄清需求 | 澄清 | 评论互动 | ✅ | `app/feedback/[id]/page.tsx`（公开评论） | 已实现 |
+| J3-US4 | 作为开发者，我希望将反馈同步到 Linear/Jira，以便纳入研发流程 | 集成 | 项目管理工具集成 | ❌ | 未发现页面/功能 | 缺失 |
+
+---
+
+## 旅程 4：Emily（客服）— 让客户感到被重视
+
+**旅程摘要**：客服代表客户提交反馈，向客户发送公开跟踪链接，后续批量通知状态。
+
+| ID | 用户故事 | 旅程步骤 | 期望能力 | 当前实现 | 对应页面/组件 | 状态 |
+|---|---|---|---|---|---|---|
+| J4-US1 | 作为客服，我希望代客户提交反馈，以便高效转述需求 | 提交反馈 | 代提交通道 | ✅ | `app/(dashboard)/feedback/new/page.tsx` | 已实现 |
+| J4-US2 | 作为客服，我希望记录客户信息，以便后续联系 | 提交反馈 | 客户信息字段 | ✅ | `app/(dashboard)/feedback/new/page.tsx` | 已实现 |
+| J4-US3 | 作为客服，我希望给客户一个公开反馈链接，以便客户跟踪进展 | 提交后 | 公开链接 | ✅ | `app/feedback/[id]/page.tsx` | 已实现 |
+| J4-US4 | 作为客服，我希望批量通知相关客户状态变更，以便提升满意度 | 通知 | 批量通知 | ❌ | 未发现页面/功能 | 缺失 |
+| J4-US5 | 作为客服，我希望与支持工具（Intercom/Zendesk）集成，以便复用现有流程 | 集成 | 支持工具集成 | ❌ | 未发现页面/功能 | 缺失 |
+
+---
+
+## 旅程 5：David（管理员）— 10 分钟部署，完全掌控
+
+**旅程摘要**：管理员完成组织创建、成员邀请、Portal 与 widget 配置；需要白标配置与运维能力。
+
+| ID | 用户故事 | 旅程步骤 | 期望能力 | 当前实现 | 对应页面/组件 | 状态 |
+|---|---|---|---|---|---|---|
+| J5-US1 | 作为管理员，我希望创建组织，以便管理不同团队 | 初始设置 | 组织创建 | ✅ | `app/(dashboard)/settings/organizations/new/page.tsx` | 已实现 |
+| J5-US2 | 作为管理员，我希望邀请成员并设置角色，以便建立协作 | 初始设置 | 成员邀请/角色管理 | ✅ | `app/(dashboard)/settings/organizations/[orgId]/members/page.tsx` | 已实现 |
+| J5-US3 | 作为管理员，我希望配置 Portal，以便对外展示反馈入口 | 配置 | Portal 设置 | ✅ | `app/(dashboard)/settings/organization/portal/page.tsx` | 已实现 |
+| J5-US4 | 作为管理员，我希望配置反馈 Widget 以便嵌入产品 | 配置 | Widget 设置 | ❌ | 未发现页面/功能 | 缺失 |
+| J5-US5 | 作为管理员，我希望配置白标域名，以便匹配品牌 | 配置 | 白标域名 | ❌ | 未发现页面/功能 | 缺失 |
+| J5-US6 | 作为管理员，我希望有初始设置向导，以便快速完成部署配置 | 初始设置 | Setup Wizard | ❌ | 未发现页面/功能 | 缺失 |
+| J5-US7 | 作为管理员，我希望有备份/更新工具，以便安全自托管 | 运维 | 自托管管理 | ❌ | 未发现页面/功能 | 缺失 |
+
+---
+
+## 旅程 6：Ryan（API 消费者）— 完美的自动化集成
+
+**旅程摘要**：通过 API 文档、API 密钥、Webhook 完成自动化集成。
+
+| ID | 用户故事 | 旅程步骤 | 期望能力 | 当前实现 | 对应页面/组件 | 状态 |
+|---|---|---|---|---|---|---|
+| J6-US1 | 作为开发者，我希望查看 API 文档，以便调用接口 | 集成准备 | API 文档 | ✅ | `app/docs/page.tsx` | 已实现 |
+| J6-US2 | 作为开发者，我希望管理 API Key，以便安全调用 | 集成准备 | API 密钥管理 | ❌ | 仅有 API 路由 `app/api/api-keys/route.ts` | 缺失 |
+| J6-US3 | 作为开发者，我希望配置 Webhook，以便事件驱动通知 | 自动化 | Webhook 管理 | ❌ | 仅有 API 路由 `app/api/webhooks/route.ts` | 缺失 |
+| J6-US4 | 作为开发者，我希望 Webhook 支持签名验证与速率限制 | 安全 | 安全/限流 | ❌ | 未发现页面/功能 | 缺失 |
+
+---
+
+## 旅程 7：Lisa（运维）— 自托管不可怕
+
+**旅程摘要**：运维人员需要健康检查、指标、日志、备份、迁移、部署文档支持。
+
+| ID | 用户故事 | 旅程步骤 | 期望能力 | 当前实现 | 对应页面/组件 | 状态 |
+|---|---|---|---|---|---|---|
+| J7-US1 | 作为运维，我希望有健康检查端点，以便监控服务 | 监控 | /health | ⚠ | 仅有 API 路由 `app/api/health/route.ts` | 部分缺失 |
+| J7-US2 | 作为运维，我希望有 Prometheus 指标端点，以便采集监控数据 | 监控 | /metrics | ❌ | 未发现页面/功能 | 缺失 |
+| J7-US3 | 作为运维，我希望有结构化日志与告警配置，以便快速排障 | 监控 | 日志/告警 | ❌ | 未发现页面/功能 | 缺失 |
+| J7-US4 | 作为运维，我希望有备份与迁移工具，以便保障数据安全 | 运维 | 备份/迁移 | ❌ | 未发现页面/功能 | 缺失 |
+| J7-US5 | 作为运维，我希望有部署/故障排除文档，以便快速恢复 | 运维 | 运维文档 | ❌ | 未发现页面/功能 | 缺失 |
+
+---
+
+## 统计概览
+
+- 已实现：17
+- 部分缺失：4
+- 缺失：16
+
+> 注：统计为粗略计数，后续可在需求管理中按模块/阶段细化拆分。
+
+---
+
+## 用户操作说明（按用户故事 ID，含入口路径）
+
+> 说明：入口路径以当前项目路由为准；若标记“缺失/部分缺失”，表示无完整可操作入口。
+
+### 旅程 1：Sarah（终端用户）
+- **J1-US1**：打开嵌入的 Widget（iframe 页面）→ 填写并提交。
+  - 入口：`/widget/[organizationId]`
+- **J1-US2**：暂无可操作入口（缺失）。
+  - 备注：附件上传组件存在但未挂接到路由。
+- **J1-US3**：提交后进入反馈详情页 → 点击“复制链接”获取跟踪链接。
+  - 入口：`/feedback/[id]`
+- **J1-US4**：暂无可操作入口（缺失）。
+  - 备注：仅有通知设置页。
+- **J1-US5**：目前仅后台列表可投票；公开列表缺失。
+  - 入口（后台）：`/feedback`
+- **J1-US6**：暂无可操作入口（缺失）。
+
+### 旅程 2：Alex（产品经理）
+- **J2-US1**：登录后台 → 查看仪表盘。
+  - 入口：`/dashboard`
+- **J2-US2**：进入反馈管理 → 使用筛选与排序控件。
+  - 入口：`/feedback`
+- **J2-US3**：在反馈列表点击进入详情。
+  - 入口：`/admin/feedback/[id]`
+- **J2-US4**：暂无可操作入口（缺失）。
+- **J2-US5**：暂无可操作入口（缺失）。
+- **J2-US6**：暂无可操作入口（缺失）。
+
+### 旅程 3：Kevin（开发者）
+- **J3-US1**：后台反馈列表进入详情查看附件。
+  - 入口：`/admin/feedback/[id]`
+- **J3-US2**：在反馈详情页查看/记录内部备注。
+  - 入口：`/admin/feedback/[id]`
+- **J3-US3**：在公开反馈详情页参与评论（登录或匿名）。
+  - 入口：`/feedback/[id]`
+- **J3-US4**：暂无可操作入口（缺失）。
+
+### 旅程 4：Emily（客服）
+- **J4-US1**：进入“代客户提交反馈”页面并提交。
+  - 入口：`/feedback/new`
+- **J4-US2**：在代提交表单中填写客户信息。
+  - 入口：`/feedback/new`
+- **J4-US3**：提交成功后打开反馈详情页复制链接发送客户。
+  - 入口：`/feedback/[id]`
+- **J4-US4**：暂无可操作入口（缺失）。
+- **J4-US5**：暂无可操作入口（缺失）。
+
+### 旅程 5：David（管理员）
+- **J5-US1**：创建组织。
+  - 入口：`/settings/organizations/new`
+- **J5-US2**：成员管理/邀请。
+  - 入口：`/settings/organizations/[orgId]/members`
+- **J5-US3**：配置 Portal。
+  - 入口：`/settings/organization/portal`
+- **J5-US4**：配置 Widget 外观与字段。
+  - 入口：暂无可操作入口（缺失）。
+- **J5-US5**：暂无可操作入口（缺失）。
+- **J5-US6**：暂无可操作入口（缺失）。
+- **J5-US7**：暂无可操作入口（缺失）。
+
+### 旅程 6：Ryan（API 消费者）
+- **J6-US1**：查看 API 文档。
+  - 入口：`/docs`
+- **J6-US2**：暂无可操作入口（缺失）。
+- **J6-US3**：暂无可操作入口（缺失）。
+- **J6-US4**：暂无可操作入口（缺失）。
+
+### 旅程 7：Lisa（运维）
+- **J7-US1**：健康检查（直接请求 API）。
+  - 入口：`/api/health`
+- **J7-US2**：暂无可操作入口（缺失）。
+- **J7-US3**：暂无可操作入口（缺失）。
+- **J7-US4**：暂无可操作入口（缺失）。
+- **J7-US5**：暂无可操作入口（缺失）。

package/drizzle.config.ts

@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) 2026 Echo Team
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import { defineConfig } from "drizzle-kit";
+import { config } from "dotenv";
+
+config({ path: ".env.local" });
+
+export default defineConfig({
+  schema: "./lib/db/schema",
+  out: "./lib/db/migrations",
+  dialect: "postgresql",
+  dbCredentials: {
+    url: process.env.DATABASE_URL!,
+  },
+  verbose: true,
+  strict: true,
+});

package/eslint.config.mjs

@@ -0,0 +1,19 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+
+const eslintConfig = defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  // Override default ignores of eslint-config-next.
+  globalIgnores([
+    // Default ignores of eslint-config-next:
+    ".next/**",
+    "out/**",
+    "build/**",
+    "next-env.d.ts",
+    ".agent/**",
+  ]),
+]);
+
+export default eslintConfig;

package/hooks/use-permissions.ts

@@ -0,0 +1,56 @@
+"use client";
+
+
+/*
+ * Copyright (c) 2026 Echo Team
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import { authClient } from "@/lib/auth/client";
+import {
+  hasAllPermissions,
+  hasPermission,
+  type Permission,
+  type UserRole,
+} from "@/lib/auth/permissions";
+
+type Session = (typeof authClient)["$Infer"]["Session"];
+
+export function useCan(
+  permission: Permission,
+  sessionOverride?: Session | null,
+): boolean {
+  const session =
+    sessionOverride === undefined ? authClient.useSession().data : sessionOverride;
+  const role = (session?.user as { role?: UserRole })?.role;
+
+  return role ? hasPermission(role, permission) : false;
+}
+
+export function useHasPermission(
+  permissions: Permission | Permission[],
+  sessionOverride?: Session | null,
+): boolean {
+  const session =
+    sessionOverride === undefined ? authClient.useSession().data : sessionOverride;
+  const role = (session?.user as { role?: UserRole })?.role;
+
+  if (!role) {
+    return false;
+  }
+
+  const list = Array.isArray(permissions) ? permissions : [permissions];
+  return hasAllPermissions(role, list);
+}

package/i18n/config.ts

@@ -0,0 +1,45 @@
+/*
+ * Copyright (c) 2026 Echo Team
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+export const DEFAULT_LOCALE = "en" as const;
+export const SUPPORTED_LOCALES = ["en", "zh-CN", "jp"] as const;
+export type AppLocale = (typeof SUPPORTED_LOCALES)[number];
+
+export const LOCALE_COOKIE_NAME = "NEXT_LOCALE";
+
+export function isSupportedLocale(value: string): value is AppLocale {
+  return (SUPPORTED_LOCALES as readonly string[]).includes(value);
+}
+
+export function normalizeLocale(value: string): AppLocale | null {
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "en" || normalized.startsWith("en-")) return "en";
+  if (normalized === "zh" || normalized === "zh-cn" || normalized.startsWith("zh-")) return "zh-CN";
+  if (normalized === "ja" || normalized === "jp" || normalized.startsWith("ja-")) return "jp";
+  return null;
+}
+
+export function getPreferredLocaleFromHeader(header: string | null): AppLocale | null {
+  if (!header) return null;
+  const locales = header.split(",").map((part) => part.split(";")[0]?.trim());
+  for (const locale of locales) {
+    if (!locale) continue;
+    const supported = normalizeLocale(locale);
+    if (supported) return supported;
+  }
+  return null;
+}

package/i18n/request.ts

@@ -0,0 +1,28 @@
+/*
+ * Copyright (c) 2026 Echo Team
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import { getRequestConfig } from "next-intl/server";
+import { resolveRequestLocale } from "./resolve-locale";
+
+export default getRequestConfig(async () => {
+  const locale = await resolveRequestLocale();
+
+  return {
+    locale,
+    messages: (await import(`../messages/${locale}.json`)).default,
+  };
+});

package/i18n/resolve-locale.ts

@@ -0,0 +1,38 @@
+/*
+ * Copyright (c) 2026 Echo Team
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import { cookies, headers } from "next/headers";
+import {
+  DEFAULT_LOCALE,
+  LOCALE_COOKIE_NAME,
+  getPreferredLocaleFromHeader,
+  isSupportedLocale,
+} from "./config";
+
+export async function resolveRequestLocale() {
+  const cookieStore = await cookies();
+  const headerStore = await headers();
+
+  const cookieLocale = cookieStore.get(LOCALE_COOKIE_NAME)?.value;
+  if (cookieLocale && isSupportedLocale(cookieLocale)) {
+    return cookieLocale;
+  }
+
+  return (
+    getPreferredLocaleFromHeader(headerStore.get("accept-language")) || DEFAULT_LOCALE
+  );
+}

package/lib/api/errors.ts

@@ -0,0 +1,62 @@
+/*
+ * Copyright (c) 2026 Echo Team
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import { NextResponse } from "next/server";
+
+export interface ApiErrorResponse {
+  error: string;
+  code: string;
+  details?: unknown;
+}
+
+export function apiError(
+  error: unknown,
+  status: number = 500,
+): NextResponse<ApiErrorResponse> {
+  if (error instanceof Error) {
+    return NextResponse.json(
+      {
+        error: error.message,
+        code: status === 400 ? "VALIDATION_ERROR" : "INTERNAL_ERROR",
+        details: process.env.NODE_ENV === "development" ? error.stack : undefined,
+      },
+      { status },
+    );
+  }
+
+  return NextResponse.json(
+    {
+      error: "An unexpected error occurred",
+      code: "INTERNAL_ERROR",
+    },
+    { status },
+  );
+}
+
+export function validationError(
+  details?: unknown,
+  message: string = "Validation failed",
+): NextResponse<ApiErrorResponse> {
+  return NextResponse.json(
+    {
+      error: message,
+      code: "VALIDATION_ERROR",
+      details,
+    },
+    { status: 400 },
+  );
+}

package/lib/auth/cli-config.ts

@@ -0,0 +1,35 @@
+/*
+ * Copyright (c) 2026 Echo Team
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import { betterAuth } from "better-auth";
+import { drizzleAdapter } from "better-auth/adapters/drizzle";
+import * as schema from "../db/schema";
+
+// CLI runs in Node (no Bun), so avoid importing the Bun SQL client here.
+const cliDbStub = {} as unknown as Record<string, unknown>;
+
+export const auth = betterAuth({
+  database: drizzleAdapter(cliDbStub, {
+    provider: "pg",
+    schema,
+  }),
+  emailAndPassword: {
+    enabled: true,
+  },
+});
+
+export default auth;

package/lib/auth/client.ts

@@ -0,0 +1,20 @@
+/*
+ * Copyright (c) 2026 Echo Team
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import { createAuthClient } from "better-auth/react";
+
+export const authClient = createAuthClient();

package/lib/auth/config.ts

@@ -0,0 +1,55 @@
+/*
+ * Copyright (c) 2026 Echo Team
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import { betterAuth } from "better-auth";
+import { drizzleAdapter } from "better-auth/adapters/drizzle";
+import { nextCookies } from "better-auth/next-js";
+import { db } from "../db";
+import * as schema from "../db/schema";
+
+if (!db) {
+  throw new Error("DATABASE_URL is not configured");
+}
+
+if (!process.env.BETTER_AUTH_SECRET && process.env.NODE_ENV !== "production") {
+  console.warn(
+    "[auth] BETTER_AUTH_SECRET is not set. Session cookies will be invalidated on server restart. " +
+    "Set BETTER_AUTH_SECRET in .env.local to fix this."
+  );
+}
+
+export const auth = betterAuth({
+  secret: process.env.BETTER_AUTH_SECRET,
+  database: drizzleAdapter(db, {
+    provider: "pg",
+    schema,
+  }),
+  user: {
+    additionalFields: {
+      role: {
+        type: "string",
+      },
+    },
+  },
+  emailAndPassword: {
+    enabled: true,
+  },
+  session: {
+    expiresIn: 60 * 60 * 24 * 30,
+  },
+  plugins: [nextCookies()],
+});

package/lib/auth/jwt-identity.ts

@@ -0,0 +1,21 @@
+/*
+ * Copyright (c) 2026 Echo Team
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+export function parseJwtIdentity(token: string) {
+  if (!token) return null;
+  return { token };
+}