Skip to content

Commit 9e25621

Browse files
hotlonghotlong
authored
Merge pull request #15 from objectql/copilot/implement-multi-tenant-management
2 parents 134a201 + b3d9e64 commit 9e25621

File tree

7 files changed

+781
-2
lines changed

7 files changed

+781
-2
lines changed

‎docs/ORGANIZATION_IMPLEMENTATION.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
# Multi-Tenant Organization Management Implementation
2+
3+
## Overview
4+
5+
This implementation adds multi-tenant organization management capabilities to ObjectQL using the Better-Auth library and its organization plugin, following Better-Auth's official specifications.
6+
7+
## Implementation Details
8+
9+
### 1. Better-Auth Plugin Integration
10+
11+
**File:** `packages/server/src/auth/auth.client.ts`
12+
13+
The organization plugin has been enabled in the Better-Auth configuration with the following features:
14+
15+
- **Dynamic Access Control**: Enabled for fine-grained permission management
16+
- **Teams**: Enabled for sub-organization grouping
17+
- **Role-Based Access Control**: Three default roles configured:
18+
- `owner`: Full access to all organization features
19+
- `admin`: Management access for members, invitations, and organization updates
20+
- `member`: Read-only access to organization and members
21+
22+
### 2. Object Schema Definitions
23+
24+
**Location:** `packages/better-auth/src/*.object.yml`
25+
26+
Seven object schemas are provided, aligned with Better-Auth's database schema:
27+
28+
1. **user.object.yml** - System users with authentication fields
29+
2. **account.object.yml** - External authentication providers (OAuth)
30+
3. **session.object.yml** - User sessions with token management
31+
4. **verification.object.yml** - Email/phone verification tokens
32+
5. **organization.object.yml** - Multi-tenant organizations
33+
6. **member.object.yml** - Organization membership with roles
34+
7. **invitation.object.yml** - Organization invitations with expiration
35+
36+
### 3. Package Exports
37+
38+
**File:** `packages/better-auth/src/index.ts`
39+
40+
The package now exports:
41+
- `BetterAuthPackage` - Package metadata
42+
- `objectDefinitions` - List of all object definition files
43+
- `getObjectDefinitionPath(filename)` - Get path to specific object definition
44+
- `getAllObjectDefinitionPaths()` - Get paths to all object definitions
45+
46+
### 4. API Endpoints
47+
48+
All organization management endpoints are automatically exposed through Better-Auth at `/api/auth/`:
49+
50+
#### Organization Management (10 endpoints)
51+
- `POST /api/auth/organization/create` - Create organization
52+
- `POST /api/auth/organization/update` - Update organization
53+
- `DELETE /api/auth/organization/delete` - Delete organization
54+
- `POST /api/auth/organization/set-active` - Set active organization
55+
- `GET /api/auth/organization/get-full` - Get full organization details
56+
- `GET /api/auth/organization/list` - List user's organizations
57+
- `GET /api/auth/organization/check-slug` - Check slug availability
58+
59+
#### Member Management (8 endpoints)
60+
- `POST /api/auth/organization/add-member` - Add member
61+
- `DELETE /api/auth/organization/remove-member` - Remove member
62+
- `POST /api/auth/organization/update-member-role` - Update member role
63+
- `GET /api/auth/organization/list-members` - List members
64+
- `GET /api/auth/organization/get-active-member` - Get current member
65+
- `GET /api/auth/organization/get-active-member-role` - Get member role
66+
- `POST /api/auth/organization/leave` - Leave organization
67+
68+
#### Invitation Management (7 endpoints)
69+
- `POST /api/auth/organization/invitation/create` - Create invitation
70+
- `POST /api/auth/organization/invitation/cancel` - Cancel invitation
71+
- `POST /api/auth/organization/invitation/accept` - Accept invitation
72+
- `POST /api/auth/organization/invitation/reject` - Reject invitation
73+
- `GET /api/auth/organization/invitation/get` - Get invitation details
74+
- `GET /api/auth/organization/invitation/list` - List organization invitations
75+
- `GET /api/auth/organization/invitation/list-user` - List user invitations
76+
77+
#### Team Management (10 endpoints)
78+
- `POST /api/auth/organization/team/create` - Create team
79+
- `POST /api/auth/organization/team/update` - Update team
80+
- `DELETE /api/auth/organization/team/remove` - Remove team
81+
- `POST /api/auth/organization/team/set-active` - Set active team
82+
- `GET /api/auth/organization/team/list` - List organization teams
83+
- `GET /api/auth/organization/team/list-user` - List user teams
84+
- `GET /api/auth/organization/team/list-members` - List team members
85+
- `POST /api/auth/organization/team/add-member` - Add team member
86+
- `DELETE /api/auth/organization/team/remove-member` - Remove team member
87+
88+
#### Access Control (5 endpoints)
89+
- `POST /api/auth/organization/role/create` - Create custom role
90+
- `POST /api/auth/organization/role/update` - Update role
91+
- `DELETE /api/auth/organization/role/delete` - Delete role
92+
- `GET /api/auth/organization/role/list` - List roles
93+
- `GET /api/auth/organization/role/get` - Get role details
94+
- `POST /api/auth/organization/has-permission` - Check permission
95+
96+
**Total: 36 organization management endpoints**
97+
98+
## Role-Based Access Control
99+
100+
### Permission Model
101+
102+
Roles are defined using the `role()` function from Better-Auth's access control plugin:
103+
104+
```typescript
105+
import { role } from "better-auth/plugins/access";
106+
107+
const ownerRole = role({
108+
organization: ['create', 'read', 'update', 'delete'],
109+
member: ['create', 'read', 'update', 'delete'],
110+
invitation: ['create', 'read', 'delete'],
111+
team: ['create', 'read', 'update', 'delete']
112+
});
113+
```
114+
115+
### Default Roles
116+
117+
1. **Owner**
118+
- Full access to all organization resources
119+
- Can manage organization settings, members, invitations, and teams
120+
- Actions: create, read, update, delete
121+
122+
2. **Admin**
123+
- Can update organization settings
124+
- Full member and invitation management
125+
- Can manage teams
126+
- Cannot delete organization
127+
128+
3. **Member**
129+
- Read-only access to organization and members
130+
- Can view teams
131+
- Cannot modify anything
132+
133+
## Database Schema
134+
135+
The organization plugin automatically creates the following database tables:
136+
137+
- `organization` - Organization details
138+
- `member` - Organization memberships
139+
- `invitation` - Pending invitations
140+
- `team` - Organization teams (if enabled)
141+
- `teamMember` - Team memberships (if enabled)
142+
- `organizationRole` - Custom roles (if dynamic access control enabled)
143+
144+
These tables integrate with Better-Auth's core tables (user, account, session, verification).
145+
146+
## Testing & Verification
147+
148+
Two verification scripts are provided in `packages/server/scripts/`:
149+
150+
1. **verify-organization-plugin.js** - Quick verification that plugin is loaded
151+
2. **inspect-organization.js** - Detailed inspection of all endpoints and plugin configuration
152+
153+
Run them after building:
154+
```bash
155+
cd packages/server
156+
npm run build
157+
node scripts/verify-organization-plugin.js
158+
node scripts/inspect-organization.js
159+
```
160+
161+
## Documentation
162+
163+
Comprehensive documentation is available in:
164+
- `packages/better-auth/README.md` - Full API reference and usage guide
165+
166+
## Security Considerations
167+
168+
✅ **Security scan passed**: No vulnerabilities detected by CodeQL
169+
✅ **Code review**: Minor suggestions for test scripts only, production code is clean
170+
✅ **TypeScript**: All code is fully typed and type-safe
171+
✅ **Better-Auth**: Uses official library with security best practices built-in
172+
173+
## Next Steps
174+
175+
To use this implementation:
176+
177+
1. Set up a PostgreSQL database
178+
2. Configure `DATABASE_URL` environment variable
179+
3. Better-Auth will automatically create the necessary tables on first use
180+
4. Use the organization endpoints to manage multi-tenant operations
181+
182+
## References
183+
184+
- [Better-Auth Documentation](https://better-auth.com)
185+
- [Better-Auth Organization Plugin](https://better-auth.com/docs/plugins/organization)
186+
- [ObjectQL Documentation](https://github.com/objectql/objectql)

‎docs/ORGANIZATION_IMPLEMENTATION_CN.md‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
# 多租户组织管理实现说明
2+
3+
## 概述
4+
5+
本实现按照 Better-Auth 规范为 ObjectQL 添加了多租户组织管理功能。
6+
7+
## 实现内容
8+
9+
### 1. Better-Auth 组织插件集成
10+
11+
**文件:** `packages/server/src/auth/auth.client.ts`
12+
13+
已在 Better-Auth 配置中启用组织插件，包含以下功能：
14+
15+
- **动态访问控制**: 支持细粒度权限管理
16+
- **团队功能**: 支持子组织分组
17+
- **基于角色的访问控制**: 配置了三个默认角色：
18+
- `owner` (所有者): 对所有组织功能拥有完全访问权限
19+
- `admin` (管理员): 对成员、邀请和组织更新具有管理访问权限
20+
- `member` (成员): 对组织和成员具有只读访问权限
21+
22+
### 2. 对象模式定义
23+
24+
**位置:** `packages/better-auth/src/*.object.yml`
25+
26+
提供了7个对象模式，与 Better-Auth 的数据库模式保持一致：
27+
28+
1. **user.object.yml** - 具有认证字段的系统用户
29+
2. **account.object.yml** - 外部认证提供商 (OAuth)
30+
3. **session.object.yml** - 带令牌管理的用户会话
31+
4. **verification.object.yml** - 邮箱/手机验证令牌
32+
5. **organization.object.yml** - 多租户组织
33+
6. **member.object.yml** - 具有角色的组织成员
34+
7. **invitation.object.yml** - 具有过期时间的组织邀请
35+
36+
### 3. 包导出
37+
38+
**文件:** `packages/better-auth/src/index.ts`
39+
40+
该包现在导出：
41+
- `BetterAuthPackage` - 包元数据
42+
- `objectDefinitions` - 所有对象定义文件列表
43+
- `getObjectDefinitionPath(filename)` - 获取特定对象定义的路径
44+
- `getAllObjectDefinitionPaths()` - 获取所有对象定义的路径
45+
46+
### 4. API 端点
47+
48+
所有组织管理端点通过 Better-Auth 在 `/api/auth/` 自动公开：
49+
50+
#### 组织管理 (10个端点)
51+
- `POST /api/auth/organization/create` - 创建组织
52+
- `POST /api/auth/organization/update` - 更新组织
53+
- `DELETE /api/auth/organization/delete` - 删除组织
54+
- `POST /api/auth/organization/set-active` - 设置活动组织
55+
- `GET /api/auth/organization/get-full` - 获取完整组织详情
56+
- `GET /api/auth/organization/list` - 列出用户的组织
57+
- `GET /api/auth/organization/check-slug` - 检查标识可用性
58+
59+
#### 成员管理 (8个端点)
60+
- `POST /api/auth/organization/add-member` - 添加成员
61+
- `DELETE /api/auth/organization/remove-member` - 移除成员
62+
- `POST /api/auth/organization/update-member-role` - 更新成员角色
63+
- `GET /api/auth/organization/list-members` - 列出成员
64+
- `GET /api/auth/organization/get-active-member` - 获取当前成员
65+
- `GET /api/auth/organization/get-active-member-role` - 获取成员角色
66+
- `POST /api/auth/organization/leave` - 离开组织
67+
68+
#### 邀请管理 (7个端点)
69+
- `POST /api/auth/organization/invitation/create` - 创建邀请
70+
- `POST /api/auth/organization/invitation/cancel` - 取消邀请
71+
- `POST /api/auth/organization/invitation/accept` - 接受邀请
72+
- `POST /api/auth/organization/invitation/reject` - 拒绝邀请
73+
- `GET /api/auth/organization/invitation/get` - 获取邀请详情
74+
- `GET /api/auth/organization/invitation/list` - 列出组织邀请
75+
- `GET /api/auth/organization/invitation/list-user` - 列出用户邀请
76+
77+
#### 团队管理 (10个端点)
78+
- `POST /api/auth/organization/team/create` - 创建团队
79+
- `POST /api/auth/organization/team/update` - 更新团队
80+
- `DELETE /api/auth/organization/team/remove` - 删除团队
81+
- `POST /api/auth/organization/team/set-active` - 设置活动团队
82+
- `GET /api/auth/organization/team/list` - 列出组织团队
83+
- `GET /api/auth/organization/team/list-user` - 列出用户团队
84+
- `GET /api/auth/organization/team/list-members` - 列出团队成员
85+
- `POST /api/auth/organization/team/add-member` - 添加团队成员
86+
- `DELETE /api/auth/organization/team/remove-member` - 移除团队成员
87+
88+
#### 访问控制 (5个端点)
89+
- `POST /api/auth/organization/role/create` - 创建自定义角色
90+
- `POST /api/auth/organization/role/update` - 更新角色
91+
- `DELETE /api/auth/organization/role/delete` - 删除角色
92+
- `GET /api/auth/organization/role/list` - 列出角色
93+
- `GET /api/auth/organization/role/get` - 获取角色详情
94+
- `POST /api/auth/organization/has-permission` - 检查权限
95+
96+
**总计：36个组织管理端点**
97+
98+
## 基于角色的访问控制
99+
100+
### 权限模型
101+
102+
使用 Better-Auth 访问控制插件的 `role()` 函数定义角色：
103+
104+
```typescript
105+
import { role } from "better-auth/plugins/access";
106+
107+
const ownerRole = role({
108+
organization: ['create', 'read', 'update', 'delete'],
109+
member: ['create', 'read', 'update', 'delete'],
110+
invitation: ['create', 'read', 'delete'],
111+
team: ['create', 'read', 'update', 'delete']
112+
});
113+
```
114+
115+
### 默认角色
116+
117+
1. **Owner (所有者)**
118+
- 对所有组织资源的完全访问权限
119+
- 可以管理组织设置、成员、邀请和团队
120+
- 操作：创建、读取、更新、删除
121+
122+
2. **Admin (管理员)**
123+
- 可以更新组织设置
124+
- 完全的成员和邀请管理权限
125+
- 可以管理团队
126+
- 不能删除组织
127+
128+
3. **Member (成员)**
129+
- 对组织和成员的只读访问权限
130+
- 可以查看团队
131+
- 不能修改任何内容
132+
133+
## 数据库模式
134+
135+
组织插件自动创建以下数据库表：
136+
137+
- `organization` - 组织详情
138+
- `member` - 组织成员关系
139+
- `invitation` - 待处理的邀请
140+
- `team` - 组织团队 (如果启用)
141+
- `teamMember` - 团队成员关系 (如果启用)
142+
- `organizationRole` - 自定义角色 (如果启用动态访问控制)
143+
144+
这些表与 Better-Auth 的核心表（user、account、session、verification）集成。
145+
146+
## 测试与验证
147+
148+
在 `packages/server/scripts/` 中提供了两个验证脚本：
149+
150+
1. **verify-organization-plugin.js** - 快速验证插件是否已加载
151+
2. **inspect-organization.js** - 详细检查所有端点和插件配置
152+
153+
构建后运行：
154+
```bash
155+
cd packages/server
156+
npm run build
157+
node scripts/verify-organization-plugin.js
158+
node scripts/inspect-organization.js
159+
```
160+
161+
## 文档
162+
163+
完整文档位于：
164+
- `packages/better-auth/README.md` - 完整的 API 参考和使用指南
165+
- `docs/ORGANIZATION_IMPLEMENTATION.md` - 详细的实现指南（英文）
166+
167+
## 安全考虑
168+
169+
✅ **安全扫描通过**: CodeQL 未检测到漏洞
170+
✅ **代码审查**: 仅对测试脚本有小建议，生产代码干净
171+
✅ **TypeScript**: 所有代码完全类型化且类型安全
172+
✅ **Better-Auth**: 使用官方库，内置安全最佳实践
173+
174+
## 下一步
175+
176+
要使用此实现：
177+
178+
1. 设置 PostgreSQL 数据库
179+
2. 配置 `DATABASE_URL` 环境变量
180+
3. Better-Auth 将在首次使用时自动创建必要的表
181+
4. 使用组织端点管理多租户操作
182+
183+
## 参考资料
184+
185+
- [Better-Auth 文档](https://better-auth.com)
186+
- [Better-Auth 组织插件](https://better-auth.com/docs/plugins/organization)
187+
- [ObjectQL 文档](https://github.com/objectql/objectql)

0 commit comments

Comments
 (0)