@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.0

package/dist/orgs/members.service.js

@@ -0,0 +1,234 @@
+import { ApiError } from "../errors.js";
+import { audit } from "../identity/audit.js";
+import { lockOrg, lockOrgAndAuthorize } from "./org-lock.js";
+/**
+ * 账号是不是某个组织的匿名访客（`org_anonymous_accounts`）。匿名访客没有登录方式，只能以 guest 身份
+ * 代表 IM 里未绑定的人：不能被授予别的角色、成为 owner、指派为 agent 负责人、加入别的组织或被移出。
+ */
+export async function isAnonymousGuest(db, accountId) {
+    const row = await db
+        .selectFrom("org_anonymous_accounts")
+        .select("account_id")
+        .where("account_id", "=", accountId)
+        .executeTakeFirst();
+    return row !== undefined;
+}
+/** 目标是匿名访客 → `409 member.anonymous_guest`。 */
+export async function rejectAnonymousGuest(db, accountId) {
+    if (await isAnonymousGuest(db, accountId)) {
+        throw new ApiError("member.anonymous_guest", "The anonymous guest of an organization cannot be given a role, ownership or agents, invited or removed");
+    }
+}
+/**
+ * 成员服务。发起人只传账号 id，角色由服务在组织行锁内实时读取，调用方无法传入过期角色。所有写操作在事务内先 `SELECT … FROM orgs WHERE id = $1 FOR NO KEY UPDATE`，
+ * 把同一组织的成员变更串行化（多副本下两个 owner 并发互相降级也恰好剩一个 owner）。
+ * 框架无关，由调用方注入 db。
+ */
+export class MembersService {
+    db;
+    offboarding;
+    /** `offboarding`：移出与离开走的离职处理（内核用 `Kernel.identity.offboarding`）。 */
+    constructor(db, offboarding) {
+        this.db = db;
+        this.offboarding = offboarding;
+    }
+    async list(orgId) {
+        const rows = await this.db
+            .selectFrom("memberships")
+            .innerJoin("accounts", "accounts.id", "memberships.account_id")
+            .leftJoin("org_anonymous_accounts", (j) => j
+            .onRef("org_anonymous_accounts.org_id", "=", "memberships.org_id")
+            .onRef("org_anonymous_accounts.account_id", "=", "memberships.account_id"))
+            .select([
+            "accounts.id",
+            "accounts.display_name",
+            "accounts.email",
+            "memberships.role",
+            "memberships.created_at",
+            "org_anonymous_accounts.account_id as anonymous_id",
+        ])
+            .where("memberships.org_id", "=", orgId)
+            .orderBy("memberships.created_at")
+            .orderBy("accounts.id")
+            .execute();
+        return rows.map((r) => ({
+            account: { id: r.id, displayName: r.display_name, email: r.email },
+            role: r.role,
+            joinedAt: r.created_at,
+            anonymous: r.anonymous_id !== null,
+        }));
+    }
+    /**
+     * 加入成员（邀请接受等，手动加入的唯一入口）；已是成员 → `member.already_exists`；匿名访客 → `member.anonymous_guest`。
+     * 同一事务删除此人在该组织的通讯录排除（Ruling A20：手动重新加入后，通讯录同步恢复照常管理此人）。
+     * `actorAccountId` 仅用于审计。
+     */
+    async add(orgId, accountId, role, actorAccountId, trx) {
+        const run = async (t) => {
+            await lockOrg(t, orgId);
+            await rejectAnonymousGuest(t, accountId);
+            if (await this.roleIn(t, orgId, accountId)) {
+                throw new ApiError("member.already_exists", "Account is already a member");
+            }
+            await t
+                .insertInto("memberships")
+                .values({ org_id: orgId, account_id: accountId, role })
+                .execute();
+            await t
+                .deleteFrom("directory_exclusions")
+                .where("org_id", "=", orgId)
+                .where("account_id", "=", accountId)
+                .execute();
+            await audit(t, {
+                actorAccountId,
+                orgId,
+                action: "org.member.added",
+                target: accountId,
+                detail: { role },
+            });
+        };
+        return trx ? run(trx) : this.db.transaction().execute(run);
+    }
+    /**
+     * 改角色：授予或撤销 owner、或改动一个 owner，只有 owner 能做（`org.owner_required`）；
+     * admin 只能在 guest / member / admin 之间调整非 owner。操作后 owner 数为 0 → `org.last_owner`。
+     * 发起人的角色在组织行锁内实时重读（spec 3.6 R5）：已不是成员或低于 admin → `forbidden`。
+     * 目标是匿名访客 → `member.anonymous_guest`。
+     */
+    async changeRole(orgId, targetId, role, actorAccountId, actorTokenId) {
+        await this.db.transaction().execute(async (t) => {
+            const { role: actorRole } = await lockOrgAndAuthorize(t, orgId, actorAccountId, "org.members.manage");
+            const before = await this.requireMember(t, orgId, targetId);
+            await rejectAnonymousGuest(t, targetId);
+            if ((role === "owner" || before === "owner") && actorRole !== "owner") {
+                throw new ApiError("org.owner_required", "Only an owner can change owner roles");
+            }
+            if (before === role)
+                return;
+            await this.setRole(t, orgId, targetId, role);
+            await this.assertHasOwner(t, orgId);
+            await audit(t, {
+                actorAccountId,
+                ...(actorTokenId !== undefined && { actorTokenId }),
+                orgId,
+                action: "org.member.role_changed",
+                target: targetId,
+                detail: { from: before, to: role },
+            });
+        });
+    }
+    /**
+     * 移出成员：权限规则同 changeRole（移除 owner 须发起人是 owner）；移除最后一个 owner → `org.last_owner`。
+     * 走离职处理（{@link Offboarding.offboard}，原因 `removed`），与之同一事务；提交后写吊销标记、发布事件。
+     * 匿名访客不能移出（`member.anonymous_guest`；不再需要匿名访问时把渠道连接改回绑定策略）。
+     */
+    async remove(orgId, targetId, actorAccountId, actorTokenId) {
+        const r = await this.db.transaction().execute(async (t) => {
+            const { role: actorRole } = await lockOrgAndAuthorize(t, orgId, actorAccountId, "org.members.manage");
+            const before = await this.requireMember(t, orgId, targetId);
+            await rejectAnonymousGuest(t, targetId);
+            if (before === "owner" && actorRole !== "owner") {
+                throw new ApiError("org.owner_required", "Only an owner can remove an owner");
+            }
+            const actor = { actorAccountId, ...(actorTokenId !== undefined && { actorTokenId }) };
+            const res = await this.offboarding.offboard(t, orgId, targetId, "removed", actor);
+            await audit(t, {
+                ...actor,
+                orgId,
+                action: "org.member.removed",
+                target: targetId,
+                detail: { role: before },
+            });
+            return res;
+        });
+        await this.offboarding.afterCommit(r);
+    }
+    /** 主动离开：走离职处理（原因 `left`）；最后一个 owner → `org.last_owner`。 */
+    async leave(orgId, accountId, actorTokenId) {
+        const r = await this.db.transaction().execute(async (t) => {
+            await lockOrg(t, orgId);
+            const before = await this.requireMember(t, orgId, accountId);
+            const actor = {
+                actorAccountId: accountId,
+                ...(actorTokenId !== undefined && { actorTokenId }),
+            };
+            const res = await this.offboarding.offboard(t, orgId, accountId, "left", actor);
+            await audit(t, {
+                ...actor,
+                orgId,
+                action: "org.member.left",
+                target: accountId,
+                detail: { role: before },
+            });
+            return res;
+        });
+        await this.offboarding.afterCommit(r);
+    }
+    /**
+     * 转让所有权：from 必须是 owner（`org.owner_required`）；to 必须是成员（`member.not_found`）且不是匿名访客
+     * （`member.anonymous_guest`）；to → owner、from → admin。
+     */
+    async transferOwnership(orgId, fromAccountId, toAccountId, actorTokenId) {
+        if (fromAccountId === toAccountId) {
+            throw new ApiError("validation_failed", "Cannot transfer ownership to yourself");
+        }
+        await this.db.transaction().execute(async (t) => {
+            await lockOrg(t, orgId);
+            const fromRole = await this.roleIn(t, orgId, fromAccountId);
+            if (fromRole !== "owner") {
+                throw new ApiError("org.owner_required", "Only an owner can transfer ownership");
+            }
+            const toRole = await this.requireMember(t, orgId, toAccountId);
+            await rejectAnonymousGuest(t, toAccountId);
+            await this.setRole(t, orgId, toAccountId, "owner");
+            await this.setRole(t, orgId, fromAccountId, "admin");
+            await audit(t, {
+                actorAccountId: fromAccountId,
+                ...(actorTokenId !== undefined && { actorTokenId }),
+                orgId,
+                action: "org.ownership_transferred",
+                target: toAccountId,
+                detail: {
+                    from: fromAccountId,
+                    to: toAccountId,
+                    fromRole: { before: fromRole, after: "admin" },
+                    toRole: { before: toRole, after: "owner" },
+                },
+            });
+        });
+    }
+    async roleIn(t, orgId, accountId) {
+        const r = await t
+            .selectFrom("memberships")
+            .select("role")
+            .where("org_id", "=", orgId)
+            .where("account_id", "=", accountId)
+            .executeTakeFirst();
+        return r?.role;
+    }
+    async requireMember(t, orgId, accountId) {
+        const role = await this.roleIn(t, orgId, accountId);
+        if (!role)
+            throw new ApiError("member.not_found", "Member not found");
+        return role;
+    }
+    async setRole(t, orgId, accountId, role) {
+        await t
+            .updateTable("memberships")
+            .set({ role, updated_at: new Date() })
+            .where("org_id", "=", orgId)
+            .where("account_id", "=", accountId)
+            .execute();
+    }
+    async assertHasOwner(t, orgId) {
+        const r = await t
+            .selectFrom("memberships")
+            .select((eb) => eb.fn.countAll().as("n"))
+            .where("org_id", "=", orgId)
+            .where("role", "=", "owner")
+            .executeTakeFirstOrThrow();
+        if (Number(r.n) === 0) {
+            throw new ApiError("org.last_owner", "An organization must keep at least one owner");
+        }
+    }
+}

package/dist/orgs/offboarding.d.ts

@@ -0,0 +1,141 @@
+import type { Logger } from "@capybara-hq/plugin-sdk";
+import type { Redis } from "ioredis";
+import { type Transaction } from "kysely";
+import type { EventLog } from "../conversations/event-log.js";
+import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
+import type { SessionService } from "../identity/sessions.js";
+import type { Maintenance } from "../runtime/maintenance.js";
+import type { ApprovalsService } from "../tools/approvals.service.js";
+import type { Credentials } from "../tools/credentials.js";
+import type { QuestionsService } from "../tools/questions.service.js";
+import type { OrgRole } from "./roles.js";
+type Trx = Transaction<KernelDatabase>;
+/** 离职原因：管理员移出、本人离开、通讯录同步判定离职。 */
+export type OffboardReason = "removed" | "left" | "directory";
+/** 一个进行中的运行。 */
+export interface InFlightRun {
+    conversationId: string;
+    runId: string;
+    status: "queued" | "running" | "waiting";
+}
+/** 一次离职处理的结果；调用方提交事务后交给 {@link Offboarding.afterCommit}。 */
+export interface OffboardResult {
+    role: OrgRole;
+    /** 在 PG 中被吊销的会话（提交后写 Redis 吊销标记）。 */
+    revokedSessionIds: string[];
+    /** 写了 cancelled 事件的会话 → 最大 seq（提交后发布）。 */
+    notify: Map<string, number>;
+    /** 此人在该组织进行中的运行（queued / running / waiting），提交后中止。 */
+    runs: InFlightRun[];
+    /** 负责的 agent 转交给的所有者；没有转交时为 null。 */
+    newOwnerId: string | null;
+    /** 此人在该组织的对话里还没销毁的沙箱（按对话 id），提交后交给 {@link OffboardingDeps.sandboxes} 销毁。 */
+    sandboxConversations: string[];
+    /** Conversations whose queued messages were deleted (`changed: queue` after commit). */
+    queueConversations: string[];
+}
+/** 运行中止：与会话中止接口（`POST .../abort`）同一套路径，`byAccountId = null` 表示系统发起。 */
+export interface OffboardingRunControl {
+    abortWaiting(conversationId: string, runId: string, byAccountId: string | null): Promise<boolean>;
+    abortIfOrphaned(conversationId: string, runId: string, byAccountId: string | null): Promise<boolean>;
+    requestAbort(runId: string, byAccountId: string | null): Promise<void>;
+}
+/** 兜底扫描：维护队列任务名、job scheduler id（不含 `:`）、周期与每次条数。 */
+export declare const OFFBOARD_SWEEP_JOB = "offboard-sweep";
+export declare const OFFBOARD_SWEEP_SCHEDULER_ID = "offboard-sweep-every-10m";
+export declare const OFFBOARD_SWEEP_EVERY_MS = 600000;
+export declare const OFFBOARD_SWEEP_BATCH = 500;
+/** 一次兜底扫描最多翻的页数（每页 {@link OFFBOARD_SWEEP_BATCH} 条），防止单次任务无限长。 */
+export declare const OFFBOARD_SWEEP_MAX_PAGES = 20;
+/** 已经广播中止的运行的标记保留时长（秒），长于扫描周期：期间扫描不再重复广播。 */
+export declare const OFFBOARD_ABORT_MARK_TTL_SECONDS = 1800;
+/** 「已请求中止」标记（Redis 键）。 */
+export declare const offboardAbortKey: (runId: string) => string;
+export interface OffboardingDeps {
+    credentials: Pick<Credentials, "clearAccount">;
+    approvals: Pick<ApprovalsService, "cancelPendingFor">;
+    questions: Pick<QuestionsService, "cancelPendingFor">;
+    /** 提交后写会话吊销标记（快速路径；鉴权以 PG `revoked_at` 为准）。 */
+    sessions?: Pick<SessionService, "markRevoked">;
+    /** 提交后发布 cancelled 事件。 */
+    eventLog?: Pick<EventLog, "notify"> & Partial<Pick<EventLog, "publishChanged">>;
+    /** 提交后中止此人在该组织进行中的运行（Ruling A7）。 */
+    runs?: OffboardingRunControl;
+    /** 兜底扫描用：读「发起人已不是成员」的进行中运行。 */
+    db?: KernelDb;
+    /** 给了就登记兜底扫描（每 10 分钟，worker 角色执行）。 */
+    maintenance?: Pick<Maintenance, "handle" | "schedule">;
+    log?: Pick<Logger, "warn">;
+    /** 记「已请求中止」标记（提交后的中止与兜底扫描都写；扫描跳过仍带标记的运行）。 */
+    redis?: Pick<Redis, "set" | "exists">;
+    /**
+     * 已加载、提供 `directory@1` 的插件名（Ruling A24：手动移出 / 离开时对其中在该组织启用的每一个写通讯录排除）。
+     * 不给时只按成员关系自身的 `directory:<插件>` 来源写。
+     */
+    directoryPlugins?: () => string[];
+    /** 兜底扫描每页条数（默认 {@link OFFBOARD_SWEEP_BATCH}，测试用）。 */
+    sweepBatch?: number;
+    /**
+     * 提交后销毁此人对话的沙箱（内核投递维护任务，由 worker 逐个 `SandboxService.destroyFor`）。不给时不销毁，
+     * 留给不活跃销毁扫描（`sandbox.limits.destroyAfterInactiveDays`）。
+     */
+    sandboxes?: {
+        destroy(conversationIds: string[]): Promise<void>;
+    };
+}
+/**
+ * 成员离职（spec 3.3）：管理员移出、本人离开与通讯录同步共用这一条路径，全部写入在调用方的同一个事务内，
+ * 要么都生效要么都不生效。Redis 吊销标记、事件发布与中止进行中的运行是提交后的尽力而为（{@link afterCommit}），
+ * 漏掉的运行由兜底扫描（{@link sweep}：发起人已不是该组织成员的进行中运行）中止。框架无关。
+ *
+ * 已接受的窄窗口：离职提交时正在进行的 OAuth token 刷新（`Credentials` 刷新锁内）可能在提交之后把此人的
+ * 个人凭据重新写回（upsert）。凭据只在此人以成员身份调用工具时使用，而其运行已被中止、成员关系已删除，
+ * 残留的凭据不会被使用；重新加入组织后会被新的连接覆盖。
+ */
+export declare class Offboarding {
+    private readonly deps;
+    constructor(deps: OffboardingDeps);
+    /**
+     * 在事务 `t` 内（调用方应已锁组织行——顺序：组织行 → 成员关系，并完成「最后一个 owner」等前置检查）：
+     * 1. 删除成员关系（非成员 → `member.not_found`；删后组织没有 owner → `org.last_owner`），清空指向该组织的会话当前组织；
+     * 2. 吊销该账号**全部**会话与个人令牌（令牌与会话是账号级的，无法只吊销「该组织下」的，按保守处理）；
+     * 3. 删除其在该组织所有连接器上的个人凭据；
+     * 4. 取消其作为处理人的 pending 审批与提问（写 cancelled 事件），记下此人在该组织进行中的运行（提交后中止）；
+     * 5. 其负责的该组织 agent 转给组织所有者（最早加入的 owner）并置 `needs_reassignment = true`；
+     * 6. 归档其在该组织各渠道连接上的 IM 话题行（重新加入后在 IM 里开始新的对话，不接着旧会话），
+     *    删除其在该组织的「以后都允许」工具授权（`tool_grants`）；
+     * 7. 手动移出或本人离开（不是同步判定离职）时写通讯录排除（Ruling A20 / A24）：对该组织启用的每个通讯录插件，
+     *    以及成员关系自身的 `directory:<插件>` 来源，不论此人当初是不是由通讯录加入（手动重新加入后再被移出也不会被同步加回）；
+     *    同步不再把此人加回，直到有人手动重新加入（{@link MembersService.add} 删除排除）；
+     * 8. 审计 `org.member.offboarded`；
+     * 9. 记下此人在该组织对话里还没销毁的沙箱（提交后销毁，尽力而为）。
+     */
+    offboard(t: Trx, orgId: string, accountId: string, reason: OffboardReason, actor?: {
+        actorAccountId?: string;
+        actorTokenId?: string;
+    }): Promise<OffboardResult>;
+    /** 要写排除的通讯录插件：该组织启用的已加载通讯录插件 ∪ 成员关系自身的 `directory:<插件>` 来源，去重排序。 */
+    private exclusionPlugins;
+    /**
+     * 提交之后：写会话吊销标记、发布 cancelled 事件、中止此人在该组织进行中的运行、投递销毁其对话沙箱的任务。
+     * 每步失败只记 warn。
+     */
+    afterCommit(r: OffboardResult): Promise<void>;
+    /**
+     * 中止一个运行，顺序同会话中止接口：waiting → 直接取消等待并写终态；孤儿 → 直接写终态；
+     * 否则经 Redis 广播中止（运行所在副本收到后结束；尚未开始的运行开始时补查中止标记）。失败只记 warn。
+     * 不像会话中止那样随后起新一轮运行：离职者的待处理消息不再处理。
+     */
+    private stopRun;
+    /**
+     * 兜底扫描（维护队列每 10 分钟）：进行中、且发起人已不是该会话所属组织成员的运行 → 中止
+     * （提交后的中止没做成时，如进程崩溃）。按 `(runs.created_at, runs.id)` 键集分页翻完（每页 500 条，
+     * 至多 20 页）：经广播中止、尚未真正结束的运行仍是进行中，若只取前 500 条，超过 500 条卡住的运行会
+     * 一直占满这一页，后面的永远轮不到。已广播中止、仍带 `capk:offboard-abort:<runId>` 标记（30 分钟）的运行跳过，
+     * 不每轮重复广播；标记过期仍未结束的再处理一次。返回本次处理（未跳过）的运行数。
+     * 现任成员（含匿名访客这样的 guest 成员）发起的运行不受影响。
+     */
+    sweep(): Promise<number>;
+    private recentlyAborted;
+}
+export {};