@goplusvn/core 0.1.75 → 0.1.76

package/src/workspace/delegation.ts

@@ -0,0 +1,400 @@
+/**
+ * Uỷ quyền quản trị người dùng — bảy bất biến D1–D7.
+ *
+ * Đây là phần lõi và cũng là phần dễ sai nhất của cả cơ chế: cho khách hàng tự
+ * tạo tài khoản mà không rào thì họ tự cấp `SUPER_ADMIN` sau 30 giây. Mỗi hàm
+ * dưới đây là một cách leo thang cụ thể đã bị bịt, không phải "kiểm tra cho chắc".
+ *
+ * D1 chứa-trong-nhánh · D2 trần quyền lúc CHẠY · D3 không tự nâng · D4 vai trò
+ * cấm uỷ quyền · D5 sở hữu trọn · D6 tài khoản được bảo vệ · D7 không tháo rào.
+ *
+ * **Một sự thật phải chấp nhận, không vá được bằng kỹ thuật** (AWS ghi thẳng
+ * trong tài liệu permissions boundary): người được uỷ quyền tạo tài khoản vẫn có
+ * thể tạo ra một tài khoản truy cập được thứ mà chính họ không truy cập được.
+ * Uỷ quyền tạo tài khoản LUÔN là một hành vi tin tưởng; D1–D7 giới hạn thiệt hại
+ * chứ không xoá bỏ nó.
+ */
+
+import { isWorkspaceAdmin } from "./scope";
+import type { WorkspaceScope } from "./types";
+
+/**
+ * Action mà chỉ TOÀN QUYỀN mới được gán đi (D4) — kể cả khi trần quyền D2 tình
+ * cờ thoả. Keycloak phát biểu y hệt cho vai trò quản trị tổ chức: "chỉ realm
+ * administrator gán được".
+ *
+ * Ai gán được `role:update` thì gán được mọi thứ khác — nên nó phải nằm đây,
+ * không phải "cân nhắc theo ngữ cảnh".
+ */
+export const DANGER_ACTIONS: readonly string[] = [
+  "role:create",
+  "role:update",
+  "role:delete",
+  "resource:create",
+  "resource:update",
+  "resource:delete",
+  "action:create",
+  "action:update",
+  "action:delete",
+  "user:manage-all",
+  "permission:assign",
+];
+
+/** Hậu tố nguy hiểm bất kể resource nào mang nó. */
+export const DANGER_SUFFIXES: readonly string[] = [
+  ":view-all-workspaces",
+  ":view-all-branches",
+  ":manage-all",
+];
+
+export type DelegationCode =
+  | "D1_OUT_OF_SCOPE"
+  | "D2_EXCEEDS_CEILING"
+  | "D3_SELF_ESCALATION"
+  | "D4_DANGEROUS_ROLE"
+  | "D5_NOT_FULLY_OWNED"
+  | "D6_PROTECTED_ACCOUNT"
+  | "D7_BOUNDARY_TAMPER"
+  | "NO_DELEGATION";
+
+export class DelegationError extends Error {
+  readonly code: DelegationCode;
+  constructor(code: DelegationCode, message: string) {
+    super(message);
+    this.name = "DelegationError";
+    this.code = code;
+  }
+}
+
+/**
+ * Người đang thao tác.
+ *
+ * `canManageAll` là lối thoát duy nhất khỏi D1–D7 — nhóm vận hành. Đừng suy ra
+ * nó từ "có nhiều membership": nhiều nhánh vẫn là bị giới hạn.
+ */
+export interface DelegationActor {
+  userId: string;
+  /** Phạm vi đã bung con cháu; `adminIds` là thứ D1/D5 dựa vào. */
+  scope: WorkspaceScope;
+  /** Toàn quyền: `user:manage-all` hoặc `*:view-all-workspaces`. Miễn mọi bất biến. */
+  canManageAll: boolean;
+  /** Tập quyền hiệu lực của chính người này, dạng `"resource:action"`. */
+  permissions: ReadonlySet<string>;
+  /** Cấp cao nhất trong các vai trò của họ — càng NHỎ càng cao. */
+  rank: number;
+}
+
+/** Người dùng bị tác động. */
+export interface DelegationTarget {
+  id: string;
+  isProtected?: boolean;
+  permissionCeilingRoleId?: string | null;
+  /** TOÀN BỘ membership của họ, không phải phần giao với phạm vi người thao tác. */
+  workspaceIds: readonly string[];
+}
+
+export interface DelegationRole {
+  id: string;
+  code: string;
+  rank: number;
+  isSystem?: boolean;
+  workspaceId?: string | null;
+  /** Quyền của vai trò, dạng `"resource:action"`. */
+  permissions: readonly string[];
+}
+
+/** Quyền này có nằm trong nhóm cấm uỷ quyền không (D4)? */
+export function isDangerousPermission(permission: string): boolean {
+  if (DANGER_ACTIONS.includes(permission)) return true;
+  return DANGER_SUFFIXES.some((suffix) => permission.endsWith(suffix));
+}
+
+/**
+ * D1 — Chứa trong nhánh. Mọi workspace gán cho người bị tạo/sửa phải nằm trong
+ * `adminIds` của người thao tác.
+ *
+ * Cố ý NÉM chứ không lặng lẽ cắt bớt danh sách: cắt bớt thì người dùng bấm lưu,
+ * thấy "thành công", rồi mới phát hiện một nửa membership không được ghi.
+ */
+export function assertWorkspacesInScope(
+  actor: DelegationActor,
+  requestedWorkspaceIds: readonly string[],
+): void {
+  if (actor.canManageAll) return;
+  if (actor.scope.adminIds.length === 0) {
+    throw new DelegationError(
+      "NO_DELEGATION",
+      "Bạn không được uỷ quyền quản trị không gian nào.",
+    );
+  }
+  const outside = requestedWorkspaceIds.filter(
+    (id) => !isWorkspaceAdmin(actor.scope, id),
+  );
+  if (outside.length > 0) {
+    throw new DelegationError(
+      "D1_OUT_OF_SCOPE",
+      `Ngoài phạm vi quản trị của bạn: ${outside.join(", ")}.`,
+    );
+  }
+}
+
+/**
+ * D3 — Không tự nâng. Không ai sửa vai trò / membership của CHÍNH MÌNH.
+ *
+ * Không có luật này thì D1 vô nghĩa: admin nhánh chỉ cần tự thêm vai trò cao hơn
+ * cho bản thân là xong.
+ */
+export function assertNotSelf(
+  actor: DelegationActor,
+  targetUserId: string,
+): void {
+  if (actor.canManageAll) return;
+  if (actor.userId === targetUserId) {
+    throw new DelegationError(
+      "D3_SELF_ESCALATION",
+      "Không thể tự sửa vai trò hoặc không gian của chính mình.",
+    );
+  }
+}
+
+/**
+ * D5 — Sửa được thì phải SỞ HỮU TRỌN. Chỉ sửa/xoá người dùng mà **toàn bộ**
+ * membership của họ nằm trong `adminIds`.
+ *
+ * Luật lỏng hơn ("giao nhau khác rỗng") sẽ cho admin khách hàng sửa được tài
+ * khoản của nhân viên vận hành đang vào hỗ trợ họ — đúng đường leo thang.
+ * Người vắt ra ngoài nhánh: ĐỌC được, không SỬA được.
+ */
+export function assertFullyOwned(
+  actor: DelegationActor,
+  target: DelegationTarget,
+): void {
+  if (actor.canManageAll) return;
+  const outside = target.workspaceIds.filter(
+    (id) => !isWorkspaceAdmin(actor.scope, id),
+  );
+  if (outside.length > 0) {
+    throw new DelegationError(
+      "D5_NOT_FULLY_OWNED",
+      "Người dùng này còn thuộc không gian ngoài phạm vi của bạn — bạn xem được nhưng không sửa được.",
+    );
+  }
+  if (target.workspaceIds.length === 0) {
+    throw new DelegationError(
+      "D5_NOT_FULLY_OWNED",
+      "Người dùng này chưa thuộc không gian nào nên không nằm trong phạm vi quản trị của bạn.",
+    );
+  }
+}
+
+/**
+ * D6 — Tài khoản được bảo vệ. Admin nhánh KHÔNG đổi mật khẩu / vô hiệu hoá / gỡ
+ * vai trò của tài khoản `isProtected`, **dù cùng workspace và dù D5 thoả**.
+ *
+ * D5 che được ca "người này vắt ra ngoài nhánh". Nó KHÔNG che được ca nhân viên
+ * vận hành được thêm vào đúng workspace khách hàng để hỗ trợ — lúc đó target chỉ
+ * thuộc nhánh của khách, D5 thoả, và admin khách reset được mật khẩu của nhân
+ * viên vận hành. Entra phải đẻ hẳn một loại AU riêng (Restricted Management) chỉ
+ * để bịt đúng lỗ này.
+ */
+export function assertNotProtected(
+  actor: DelegationActor,
+  target: DelegationTarget,
+): void {
+  if (actor.canManageAll) return;
+  if (target.isProtected) {
+    throw new DelegationError(
+      "D6_PROTECTED_ACCOUNT",
+      "Tài khoản này được bảo vệ — chỉ quản trị toàn hệ thống thao tác được.",
+    );
+  }
+}
+
+/**
+ * D2 + D4 — vai trò có gán đi được không.
+ *
+ * D2 (trần quyền): vai trò không được chứa quyền mà chính người gán không có.
+ * D4 (cấm uỷ quyền): vai trò chứa action nguy hiểm thì chỉ toàn quyền gán được,
+ * kể cả khi D2 tình cờ thoả.
+ * Kèm luật `rank`: chỉ gán được vai trò THẤP HƠN cấp của mình, và không gán được
+ * vai trò hệ thống hay vai trò thuộc nhánh khác.
+ */
+export function assertRoleAssignable(
+  actor: DelegationActor,
+  role: DelegationRole,
+): void {
+  if (actor.canManageAll) return;
+
+  const dangerous = role.permissions.filter(isDangerousPermission);
+  if (dangerous.length > 0) {
+    throw new DelegationError(
+      "D4_DANGEROUS_ROLE",
+      `Vai trò "${role.code}" chứa quyền quản trị hệ thống (${dangerous.join(", ")}) — chỉ quản trị toàn hệ thống gán được.`,
+    );
+  }
+
+  if (role.isSystem) {
+    throw new DelegationError(
+      "D4_DANGEROUS_ROLE",
+      `Vai trò "${role.code}" là vai trò hệ thống — chỉ quản trị toàn hệ thống gán được.`,
+    );
+  }
+
+  if (role.rank <= actor.rank) {
+    throw new DelegationError(
+      "D2_EXCEEDS_CEILING",
+      `Vai trò "${role.code}" có cấp ngang hoặc cao hơn bạn — không gán được.`,
+    );
+  }
+
+  const exceeded = role.permissions.filter((p) => !actor.permissions.has(p));
+  if (exceeded.length > 0) {
+    throw new DelegationError(
+      "D2_EXCEEDS_CEILING",
+      `Vai trò "${role.code}" chứa quyền bạn không có: ${exceeded.slice(0, 5).join(", ")}${exceeded.length > 5 ? "…" : ""}.`,
+    );
+  }
+
+  if (role.workspaceId && !isWorkspaceAdmin(actor.scope, role.workspaceId)) {
+    throw new DelegationError(
+      "D1_OUT_OF_SCOPE",
+      `Vai trò "${role.code}" thuộc không gian ngoài phạm vi của bạn.`,
+    );
+  }
+}
+
+/** Lọc danh sách vai trò còn lại những cái GÁN ĐƯỢC — dùng cho picker (D2∧D4). */
+export function assignableRoles<T extends DelegationRole>(
+  actor: DelegationActor,
+  roles: readonly T[],
+): T[] {
+  return roles.filter((role) => {
+    try {
+      assertRoleAssignable(actor, role);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+}
+
+/**
+ * D2 bản CHẠY — quyền hiệu lực = GIAO của quyền vai trò và trần quyền.
+ *
+ * Bản chỉ-kiểm-lúc-gán là chưa đủ: người gán bị thu hồi quyền sau đó thì tài
+ * khoản họ đã tạo **vẫn giữ nguyên quyền cũ**. AWS giải bằng permissions
+ * boundary đánh giá mỗi request; đây là bản rút gọn của đúng ý đó.
+ *
+ * `ceiling === null` (không có trần) ⇒ trả nguyên quyền vai trò.
+ */
+export function applyPermissionCeiling(
+  rolePermissions: readonly string[],
+  ceilingPermissions: readonly string[] | null | undefined,
+): string[] {
+  if (!ceilingPermissions) return [...rolePermissions];
+  const ceiling = new Set(ceilingPermissions);
+  return rolePermissions.filter((p) => ceiling.has(p));
+}
+
+/** Thay đổi đang được yêu cầu trên một người dùng — đầu vào của D7. */
+export interface DelegationChanges {
+  /** Đổi trần quyền của target. */
+  permissionCeilingRoleId?: string | null;
+  /** Đổi cờ bảo vệ. */
+  isProtected?: boolean;
+  /** Danh sách membership sau khi sửa. */
+  workspaceIds?: readonly string[];
+}
+
+/**
+ * D7 — Không tháo được rào. Deny tường minh, thắng mọi thứ khác.
+ *
+ * Ba đường vòng bị bịt ở đây, và cả ba đều là đường vòng THẬT (AWS phải viết
+ * riêng hai policy `NoBoundaryPolicyEdit` + `NoBoundaryUserDelete` cho hai cái
+ * đầu — thiếu chúng thì cái trần chỉ là gợi ý):
+ *  1. sửa / gỡ trần quyền của người khác,
+ *  2. tự bật/tắt cờ bảo vệ,
+ *  3. gỡ membership của người khác để đẩy họ ra khỏi phạm vi rồi thao tác tiếp.
+ */
+export function assertBoundaryIntact(
+  actor: DelegationActor,
+  target: DelegationTarget,
+  changes: DelegationChanges,
+): void {
+  if (actor.canManageAll) return;
+
+  if (
+    changes.permissionCeilingRoleId !== undefined &&
+    changes.permissionCeilingRoleId !== target.permissionCeilingRoleId
+  ) {
+    throw new DelegationError(
+      "D7_BOUNDARY_TAMPER",
+      "Không thể sửa hoặc gỡ trần quyền — chỉ quản trị toàn hệ thống làm được.",
+    );
+  }
+
+  if (
+    changes.isProtected !== undefined &&
+    changes.isProtected !== Boolean(target.isProtected)
+  ) {
+    throw new DelegationError(
+      "D7_BOUNDARY_TAMPER",
+      "Không thể đổi trạng thái bảo vệ của tài khoản.",
+    );
+  }
+
+  if (changes.workspaceIds) {
+    // Membership NGOÀI phạm vi của người thao tác phải được giữ nguyên. Cho phép
+    // gỡ nghĩa là cho phép đẩy nạn nhân ra khỏi nhánh khác rồi D5 tự nhiên thoả.
+    const untouchable = target.workspaceIds.filter(
+      (id) => !isWorkspaceAdmin(actor.scope, id),
+    );
+    const kept = new Set(changes.workspaceIds);
+    const removed = untouchable.filter((id) => !kept.has(id));
+    if (removed.length > 0) {
+      throw new DelegationError(
+        "D7_BOUNDARY_TAMPER",
+        "Không thể gỡ người dùng khỏi không gian nằm ngoài phạm vi quản trị của bạn.",
+      );
+    }
+  }
+}
+
+/**
+ * Cổng đầy đủ cho đường SỬA một người dùng — gọi đúng một hàm này ở route thay
+ * vì nhớ gọi sáu hàm rời (quên một cái là thủng một bất biến).
+ */
+export function assertCanUpdateUser(
+  actor: DelegationActor,
+  target: DelegationTarget,
+  changes: DelegationChanges = {},
+): void {
+  assertNotSelf(actor, target.id);
+  assertNotProtected(actor, target);
+  assertFullyOwned(actor, target);
+  assertBoundaryIntact(actor, target, changes);
+  if (changes.workspaceIds) {
+    assertWorkspacesInScope(actor, changes.workspaceIds);
+  }
+}
+
+/** Cổng đầy đủ cho đường TẠO người dùng. */
+export function assertCanCreateUser(
+  actor: DelegationActor,
+  workspaceIds: readonly string[],
+  roles: readonly DelegationRole[] = [],
+): void {
+  assertWorkspacesInScope(actor, workspaceIds);
+  if (!actor.canManageAll && workspaceIds.length === 0) {
+    throw new DelegationError(
+      "D1_OUT_OF_SCOPE",
+      "Phải chọn ít nhất một không gian trong phạm vi quản trị của bạn.",
+    );
+  }
+  for (const role of roles) assertRoleAssignable(actor, role);
+}
+
+/** Có được uỷ quyền quản trị người dùng ở đâu đó không — dùng để bật/tắt nút "Thêm". */
+export function canDelegateUsers(actor: DelegationActor): boolean {
+  return actor.canManageAll || actor.scope.adminIds.length > 0;
+}

package/src/workspace/guard.ts

@@ -0,0 +1,138 @@
+import { resolveAmbientScope } from "./context";
+import { scopedWhere, workspaceScopeField } from "./scope";
+import type { WorkspaceScope } from "./types";
+
+/**
+ * LỚP 2 — lưới an toàn ở tầng ORM (mô hình Odoo/NocoBase): route mới quên lọc
+ * phạm vi thì vẫn không lộ dữ liệu.
+ *
+ * Chỉ chạm thao tác ĐỌC, chỉ trên model được khai, và chỉ khi có ScopeContext —
+ * ngoài context (RSC page, cron, webhook, script) extension bất động, nên tác
+ * vụ nền không bị cắt dữ liệu bất ngờ.
+ *
+ *   db.$extends(createScopeGuardExtension({
+ *     models: {
+ *       Receipt:      {},                              // cột phạm vi mặc định
+ *       GoodsReceipt: { relation: "warehouse" },       // scope qua quan hệ
+ *       SalesOrder:   { crossScopeRead: true },        // đọc chéo hợp lệ
+ *     },
+ *   }))
+ *
+ * CẢNH BÁO: model đưa vào `models` PHẢI có cột phạm vi, hoặc phải khai
+ * `relation`/`where`. Chèn điều kiện lên cột không tồn tại là Prisma ném
+ * validation error cho MỌI thao tác đọc của user bị scope — hỏng cả nghiệp vụ,
+ * không chỉ hỏng bộ lọc.
+ */
+
+export interface ModelScopeConfig {
+  /** Cột mang phạm vi; mặc định lấy từ `configureWorkspaces({ scopeField })`. */
+  field?: string;
+  /** Model không có cột phạm vi thì đi qua quan hệ, VD `"warehouse"`. */
+  relation?: string;
+  /**
+   * **Δ2 — đọc chéo có kiểm soát.** Model có luồng liên không gian HỢP LỆ (bán
+   * lại chọn đơn nguồn chi nhánh khác, lịch sử đơn của khách) thì bật cờ này:
+   * thao tác đọc đi thẳng, thao tác **ghi hàng loạt vẫn bị kẹp**.
+   *
+   * NetSuite gọi đúng thứ này là `Allow Cross-Subsidiary Record Viewing` — xem
+   * được, sửa không được. Trước đây ta xử bằng cách **bỏ model ra khỏi danh
+   * sách guard**, tức là vừa xem chéo vừa SỬA chéo được. Cờ này thay cho cách
+   * đó: mỗi ngoại lệ có đúng một dòng khai, kèm lý do trong code.
+   *
+   * GIỚI HẠN THẬT, phải biết: `update`/`delete` một dòng dùng `where` unique
+   * nên guard KHÔNG chèn điều kiện vào được — service phải tự gọi
+   * `canAccessWorkspace(scope, record.workspaceId)` trước khi ghi. Guard chỉ
+   * kẹp được `updateMany`/`deleteMany`.
+   */
+  crossScopeRead?: boolean;
+  /** Điều kiện guard tự viết; trả `null` để rơi về mặc định. */
+  where?: (scope: WorkspaceScope) => Record<string, unknown> | null;
+}
+
+export interface ScopeGuardOptions {
+  /** Tên model Prisma (đúng chữ hoa/thường như trong schema) → cấu hình. */
+  models: Record<string, ModelScopeConfig> | string[];
+  /** Mặc định: các thao tác đọc nhiều dòng. */
+  operations?: string[];
+  /**
+   * Thao tác ghi hàng loạt bị kẹp `where` — kể cả model `crossScopeRead`. Ghi
+   * một dòng (`update`/`delete`) không nằm ở đây vì `where` của chúng chỉ nhận
+   * unique field.
+   */
+  writeOperations?: string[];
+}
+
+/**
+ * findUnique* cố ý không guard: `where` của nó chỉ nhận unique field, chèn thêm
+ * điều kiện là Prisma từ chối. Trang chi tiết guard bằng `canAccessWorkspace`.
+ */
+const DEFAULT_OPERATIONS = [
+  "findMany",
+  "findFirst",
+  "findFirstOrThrow",
+  "count",
+  "aggregate",
+  "groupBy",
+];
+
+const DEFAULT_WRITE_OPERATIONS = ["updateMany", "deleteMany"];
+
+export function createScopeGuardExtension(options: ScopeGuardOptions) {
+  const models: Record<string, ModelScopeConfig> = Array.isArray(options.models)
+    ? Object.fromEntries(options.models.map((name) => [name, {}]))
+    : options.models;
+  const operations = new Set(options.operations ?? DEFAULT_OPERATIONS);
+  const writeOperations = new Set(
+    options.writeOperations ?? DEFAULT_WRITE_OPERATIONS,
+  );
+
+  return {
+    name: "workspace-guard",
+    query: {
+      $allModels: {
+        // Chữ ký thật do Prisma sinh theo schema của từng app; khai chặt ở core
+        // sẽ không assignable ở phía app (kiểu hẹp hơn, contravariance).
+        /* eslint-disable @typescript-eslint/no-explicit-any */
+        async $allOperations({
+          model,
+          operation,
+          args,
+          query,
+        }: {
+          model?: string;
+          operation: string;
+          args: any;
+          query: (args: any) => Promise<any>;
+        }): Promise<any> {
+          const config = model ? models[model] : undefined;
+          if (!config) return query(args);
+
+          const isRead = operations.has(operation);
+          const isWrite = writeOperations.has(operation);
+          if (!isRead && !isWrite) return query(args);
+          // Đọc chéo được cho phép; GHI thì không, kể cả trên model đó.
+          if (isRead && config.crossScopeRead) return query(args);
+
+          const scopePromise = resolveAmbientScope<WorkspaceScope>();
+          if (!scopePromise) return query(args);
+
+          const scope = await scopePromise;
+          if (scope.canViewAll) return query(args);
+
+          const guard =
+            config.where?.(scope) ??
+            scopedWhere(scope, {
+              field: config.field ?? workspaceScopeField(),
+              relation: config.relation,
+            });
+          const prevWhere = args?.where;
+          return query({
+            ...args,
+            where: prevWhere ? { AND: [prevWhere, guard] } : guard,
+          });
+        },
+        /* eslint-enable @typescript-eslint/no-explicit-any */
+      },
+    },
+  };
+}

package/src/workspace/index.ts

@@ -0,0 +1,157 @@
+/**
+ * Không gian làm việc (workspace) — phạm vi dữ liệu tổng quát.
+ *
+ * Chi nhánh / đơn vị / phòng ban / tổ chức là **một cây có nhãn `kind`**, không
+ * phải bốn cơ chế. Ba lớp cưỡng chế:
+ *
+ *   Lớp 1 (tường minh): `getWorkspaceScope(session)` + `scopedWhere(scope)`
+ *   trong page/route/service. Đây mới là lớp làm việc chính.
+ *
+ *   Lớp 2 (lưới an toàn): `createScopeGuardExtension` cắm vào Prisma, tự AND
+ *   điều kiện phạm vi cho thao tác đọc trên model được khai — cứu chỗ quên.
+ *
+ *   Lớp 3 (uỷ quyền): người dùng và vai trò KHÔNG phải chứng từ, không xử được
+ *   bằng `where workspaceId` — ai gán quyền được cho ai là một bài toán khác.
+ *   Bộ luật riêng D1–D7 nằm ở `./delegation`.
+ *
+ * App cấu hình một lần ở composition root và import phạm vi qua đúng file đó
+ * (`src/lib/branch-scope.ts`): engine là singleton, import thẳng từ core sẽ lấy
+ * được hàm nhưng bỏ lỡ lời gọi cấu hình.
+ *
+ * `@goerp/core/branch-scope` vẫn chạy y nguyên — nó là lớp adapter mỏng của
+ * module này, dùng CHUNG một AsyncLocalStorage.
+ */
+export {
+  configureWorkspaces,
+  resetWorkspaceConfig,
+  getWorkspaceConfig,
+  workspaceScopeField,
+  canViewAllWorkspaces,
+  createWorkspaceScope,
+  getWorkspaceScope,
+  canAccessWorkspace,
+  isWorkspaceAdmin,
+  hasAdminScope,
+  scopedWhere,
+  memberScopeWhere,
+  scopeLevelWhere,
+  scopeLevelAtLeast,
+  clampScopeFilter,
+  clampToAdminScope,
+} from "./scope";
+
+export {
+  runWithScope,
+  getScopeContext,
+  resolveAmbientScope,
+  runWithoutScope,
+  type ScopeContext,
+} from "./context";
+
+export {
+  createScopeGuardExtension,
+  type ScopeGuardOptions,
+  type ModelScopeConfig,
+} from "./guard";
+
+export {
+  PATH_SEPARATOR,
+  ROOT_PATH,
+  buildPath,
+  normalizePath,
+  pathSegments,
+  pathDepth,
+  selfIdFromPath,
+  parentIdFromPath,
+  isInSubtree,
+  subtreePrefix,
+  selfAndDescendants,
+  repathSubtree,
+  assertNoCycle,
+  assertDepthLimit,
+  WorkspaceTreeError,
+} from "./tree";
+
+export {
+  createWorkspace,
+  moveWorkspace,
+  listSubtree,
+  deactivateSubtree,
+  buildTree,
+  type WorkspaceServiceDb,
+  type WorkspaceServiceOptions,
+  type CreateWorkspaceInput,
+  type MoveWorkspaceInput,
+  type WorkspaceTreeItem,
+  type WorkspaceTreeOf,
+} from "./service";
+
+export {
+  DANGER_ACTIONS,
+  DANGER_SUFFIXES,
+  DelegationError,
+  isDangerousPermission,
+  assertWorkspacesInScope,
+  assertNotSelf,
+  assertFullyOwned,
+  assertNotProtected,
+  assertRoleAssignable,
+  assignableRoles,
+  applyPermissionCeiling,
+  assertBoundaryIntact,
+  assertCanUpdateUser,
+  assertCanCreateUser,
+  canDelegateUsers,
+  type DelegationCode,
+  type DelegationActor,
+  type DelegationTarget,
+  type DelegationRole,
+  type DelegationChanges,
+} from "./delegation";
+
+export {
+  createWorkspaceCollectionHandlers,
+  createWorkspaceItemHandlers,
+  createWorkspaceMoveHandler,
+  type WorkspaceHandlerDeps,
+} from "./route-handlers";
+
+export {
+  WorkspaceTreeView,
+  countTreeNodes,
+  type WorkspaceTreeNode,
+  type WorkspaceTreeViewProps,
+} from "./components/workspace-tree-view";
+
+export {
+  WorkspaceSwitcher,
+  type WorkspaceOption,
+  type WorkspaceSwitcherProps,
+} from "./components/workspace-switcher";
+
+export {
+  ScopeLevelSelect,
+  scopeLevelLabel,
+  type ScopeLevelSelectProps,
+} from "./components/scope-level-select";
+
+export {
+  WorkspaceListPage,
+  type WorkspaceListPageProps,
+} from "./pages/workspace-list-page";
+
+export {
+  NO_WORKSPACE_ACCESS,
+  DEFAULT_MAX_DEPTH,
+  DEFAULT_MAX_CHILDREN,
+  SCOPE_LEVELS,
+  SCOPE_LEVEL_LABELS,
+  type WorkspaceKind,
+  type WorkspaceKindConfig,
+  type WorkspaceNode,
+  type WorkspaceMembership,
+  type WorkspaceScope,
+  type WorkspaceScopeConfig,
+  type WorkspaceScopeDb,
+  type ScopeLevel,
+} from "./types";