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

package/dist/orgs/offboarding.js

@@ -0,0 +1,398 @@
+import { sql } from "kysely";
+import { ApiError } from "../errors.js";
+import { enabledExtensionsQuery } from "../extensions/enabled.js";
+import { audit } from "../identity/audit.js";
+/** 兜底扫描：维护队列任务名、job scheduler id（不含 `:`）、周期与每次条数。 */
+export const OFFBOARD_SWEEP_JOB = "offboard-sweep";
+export const OFFBOARD_SWEEP_SCHEDULER_ID = "offboard-sweep-every-10m";
+export const OFFBOARD_SWEEP_EVERY_MS = 600_000;
+export const OFFBOARD_SWEEP_BATCH = 500;
+/** 一次兜底扫描最多翻的页数（每页 {@link OFFBOARD_SWEEP_BATCH} 条），防止单次任务无限长。 */
+export const OFFBOARD_SWEEP_MAX_PAGES = 20;
+/** 已经广播中止的运行的标记保留时长（秒），长于扫描周期：期间扫描不再重复广播。 */
+export const OFFBOARD_ABORT_MARK_TTL_SECONDS = 1800;
+/** 「已请求中止」标记（Redis 键）。 */
+export const offboardAbortKey = (runId) => `capk:offboard-abort:${runId}`;
+const ACTIVE = ["queued", "running", "waiting"];
+/** 通讯录同步加入的成员关系的 `source` 前缀（`directory:<插件名>`）。 */
+const DIRECTORY_SOURCE_PREFIX = "directory:";
+/**
+ * 成员离职（spec 3.3）：管理员移出、本人离开与通讯录同步共用这一条路径，全部写入在调用方的同一个事务内，
+ * 要么都生效要么都不生效。Redis 吊销标记、事件发布与中止进行中的运行是提交后的尽力而为（{@link afterCommit}），
+ * 漏掉的运行由兜底扫描（{@link sweep}：发起人已不是该组织成员的进行中运行）中止。框架无关。
+ *
+ * 已接受的窄窗口：离职提交时正在进行的 OAuth token 刷新（`Credentials` 刷新锁内）可能在提交之后把此人的
+ * 个人凭据重新写回（upsert）。凭据只在此人以成员身份调用工具时使用，而其运行已被中止、成员关系已删除，
+ * 残留的凭据不会被使用；重新加入组织后会被新的连接覆盖。
+ */
+export class Offboarding {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+        deps.maintenance?.schedule({
+            id: OFFBOARD_SWEEP_SCHEDULER_ID,
+            name: OFFBOARD_SWEEP_JOB,
+            everyMs: () => OFFBOARD_SWEEP_EVERY_MS,
+        });
+        deps.maintenance?.handle(OFFBOARD_SWEEP_JOB, async () => {
+            await this.sweep();
+        });
+    }
+    /**
+     * 在事务 `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. 记下此人在该组织对话里还没销毁的沙箱（提交后销毁，尽力而为）。
+     */
+    async offboard(t, orgId, accountId, reason, actor = {}) {
+        const deleted = await t
+            .deleteFrom("memberships")
+            .where("org_id", "=", orgId)
+            .where("account_id", "=", accountId)
+            .returning(["role", "source"])
+            .executeTakeFirst();
+        if (!deleted)
+            throw new ApiError("member.not_found", "Member not found");
+        // lock the member's agents in id order, right after the membership and before anything that
+        // appends to a conversation (approvals, questions lock conversation rows): a dispatch takes
+        // FOR SHARE on two agent rows in id order and then appends to the parent conversation, so
+        // offboarding goes agents -> conversations the same way (batch 10 m4, batch 11 m1); an UPDATE
+        // alone would lock in scan order. These rows (and the conversations below) are updated, never
+        // deleted or re-keyed, so NO KEY UPDATE: it still excludes FOR SHARE and other writers, but not
+        // the foreign key checks (FOR KEY SHARE) of a transaction that writes rows referencing them,
+        // which may already hold a conversation row this transaction waits for (40P01)
+        await t
+            .selectFrom("agents")
+            .select("id")
+            .where("org_id", "=", orgId)
+            .where("owner_account_id", "=", accountId)
+            .where("deleted_at", "is", null)
+            .orderBy("id")
+            .forNoKeyUpdate()
+            .execute();
+        // then the member's conversations in id order, before any of their queue rows (final review
+        // m2): queue dispatch, send-now and remove lock a conversation, then its queue rows; deleting
+        // the rows first and updating the conversations after could deadlock with them (40P01)
+        await t
+            .selectFrom("conversations")
+            .select("id")
+            .where("org_id", "=", orgId)
+            .where("account_id", "=", accountId)
+            .orderBy("id")
+            .forNoKeyUpdate()
+            .execute();
+        const owner = await t
+            .selectFrom("memberships")
+            .select("account_id")
+            .where("org_id", "=", orgId)
+            .where("role", "=", "owner")
+            .orderBy("created_at")
+            .orderBy("account_id")
+            .limit(1)
+            .executeTakeFirst();
+        if (!owner) {
+            throw new ApiError("org.last_owner", "An organization must keep at least one owner");
+        }
+        await t
+            .updateTable("sessions")
+            .set({ current_org_id: null })
+            .where("account_id", "=", accountId)
+            .where("current_org_id", "=", orgId)
+            .execute();
+        const sessions = await t
+            .updateTable("sessions")
+            .set({ revoked_at: sql `now()` })
+            .where("account_id", "=", accountId)
+            .where("revoked_at", "is", null)
+            .returning("id")
+            .execute();
+        const tokens = await t
+            .updateTable("api_tokens")
+            .set({ revoked_at: sql `now()` })
+            .where("kind", "=", "personal")
+            .where("account_id", "=", accountId)
+            .where("revoked_at", "is", null)
+            .returning("id")
+            .execute();
+        const credentials = await this.deps.credentials.clearAccount(orgId, accountId, t);
+        const approvals = await this.deps.approvals.cancelPendingFor(t, orgId, accountId);
+        const questions = await this.deps.questions.cancelPendingFor(t, orgId, accountId);
+        const notify = new Map(approvals.seqs);
+        for (const [c, seq] of questions.seqs)
+            notify.set(c, Math.max(notify.get(c) ?? 0, seq));
+        const runs = await t
+            .selectFrom("runs")
+            .innerJoin("conversations", "conversations.id", "runs.conversation_id")
+            .select(["runs.id", "runs.conversation_id", "runs.status"])
+            .where("conversations.org_id", "=", orgId)
+            // 评测回放的隐藏对话由评测 worker 驱动（不执行工具），随评测运行停下，不在这里中止。
+            // 评测运行的创建者离开组织也不取消评测运行（Ruling S1-b）：管理员发起的评测运行是组织的工作，
+            // 只有取消、删除评测集、删除组织或 agent 才会停下（见 evals/budget.ts cancelEvalRuns）
+            // a removed member's sub-agents run with their identity and credentials: stopped too
+            .where("conversations.kind", "in", ["chat", "subagent"])
+            .where("runs.status", "in", ACTIVE)
+            .where((eb) => eb.or([
+            eb("runs.trigger_account_id", "=", accountId),
+            eb("conversations.account_id", "=", accountId),
+        ]))
+            .execute();
+        const agents = await t
+            .updateTable("agents")
+            .set({
+            owner_account_id: owner.account_id,
+            needs_reassignment: true,
+            updated_at: sql `now()`,
+        })
+            .where("org_id", "=", orgId)
+            .where("owner_account_id", "=", accountId)
+            .where("deleted_at", "is", null)
+            .returning("id")
+            .execute();
+        const threads = await t
+            .updateTable("channel_threads")
+            .set({ archived_at: sql `now()` })
+            .where("account_id", "=", accountId)
+            .where("archived_at", "is", null)
+            .where("connection_id", "in", (eb) => eb.selectFrom("channel_connections").select("id").where("org_id", "=", orgId))
+            .executeTakeFirst();
+        const grants = await t
+            .deleteFrom("tool_grants")
+            .where("org_id", "=", orgId)
+            .where("account_id", "=", accountId)
+            .executeTakeFirst();
+        const excluded = reason === "directory" ? [] : await this.exclusionPlugins(t, orgId, deleted.source);
+        if (excluded.length > 0) {
+            await t
+                .insertInto("directory_exclusions")
+                .values(excluded.map((plugin) => ({
+                org_id: orgId,
+                account_id: accountId,
+                plugin,
+                created_by: actor.actorAccountId ?? null,
+            })))
+                .onConflict((oc) => oc.columns(["org_id", "account_id", "plugin"]).doNothing())
+                .execute();
+        }
+        // Queued messages never go out after their author leaves (they also hold `@` resource bodies
+        // read with the person's credentials): deleted here, so no dispatch can pick them up.
+        const queued = await t
+            .deleteFrom("conversation_queue")
+            .where("conversation_id", "in", (eb) => eb
+            .selectFrom("conversations")
+            .select("id")
+            .where("org_id", "=", orgId)
+            .where("account_id", "=", accountId))
+            .returning("conversation_id")
+            .execute();
+        const queueConversations = [...new Set(queued.map((r) => r.conversation_id))];
+        if (queueConversations.length > 0) {
+            await t
+                .updateTable("conversations")
+                .set({ queue_paused: false, queue_pause_reason: null })
+                .where("id", "in", queueConversations)
+                .execute();
+        }
+        const sandboxes = await t
+            .selectFrom("sandboxes")
+            .innerJoin("conversations", "conversations.id", "sandboxes.conversation_id")
+            .select("sandboxes.conversation_id")
+            .where("conversations.org_id", "=", orgId)
+            .where("conversations.account_id", "=", accountId)
+            .where("sandboxes.status", "<>", "destroyed")
+            .execute();
+        await audit(t, {
+            ...(actor.actorAccountId !== undefined && { actorAccountId: actor.actorAccountId }),
+            ...(actor.actorTokenId !== undefined && { actorTokenId: actor.actorTokenId }),
+            orgId,
+            action: "org.member.offboarded",
+            target: accountId,
+            detail: {
+                reason,
+                role: deleted.role,
+                sessionsRevoked: sessions.length,
+                tokensRevoked: tokens.length,
+                credentialsDeleted: credentials,
+                approvalsCancelled: approvals.records.length,
+                questionsCancelled: questions.records.length,
+                runsToStop: runs.length,
+                agentsReassigned: agents.map((a) => a.id),
+                newOwner: agents.length > 0 ? owner.account_id : null,
+                channelThreadsArchived: Number(threads.numUpdatedRows),
+                toolGrantsDeleted: Number(grants.numDeletedRows),
+                ...(excluded.length > 0 && { directoryExcluded: excluded }),
+                ...(sandboxes.length > 0 && { sandboxesToDestroy: sandboxes.length }),
+                ...(queued.length > 0 && { queuedMessagesDeleted: queued.length }),
+            },
+        });
+        return {
+            role: deleted.role,
+            revokedSessionIds: sessions.map((s) => s.id),
+            notify,
+            runs: runs.map((r) => ({
+                conversationId: r.conversation_id,
+                runId: r.id,
+                status: r.status,
+            })),
+            newOwnerId: agents.length > 0 ? owner.account_id : null,
+            sandboxConversations: sandboxes.map((r) => r.conversation_id),
+            queueConversations,
+        };
+    }
+    /** 要写排除的通讯录插件：该组织启用的已加载通讯录插件 ∪ 成员关系自身的 `directory:<插件>` 来源，去重排序。 */
+    async exclusionPlugins(t, orgId, source) {
+        const out = new Set();
+        if (source?.startsWith(DIRECTORY_SOURCE_PREFIX)) {
+            out.add(source.slice(DIRECTORY_SOURCE_PREFIX.length));
+        }
+        const loaded = this.deps.directoryPlugins?.() ?? [];
+        if (loaded.length > 0) {
+            const rows = await t
+                .selectFrom(enabledExtensionsQuery(t, orgId).as("en"))
+                .select("en.plugin")
+                .where("en.plugin", "in", loaded)
+                .execute();
+            for (const r of rows)
+                out.add(r.plugin);
+        }
+        return [...out].sort();
+    }
+    /**
+     * 提交之后：写会话吊销标记、发布 cancelled 事件、中止此人在该组织进行中的运行、投递销毁其对话沙箱的任务。
+     * 每步失败只记 warn。
+     */
+    async afterCommit(r) {
+        const { sessions, eventLog, log } = this.deps;
+        try {
+            await sessions?.markRevoked(r.revokedSessionIds);
+        }
+        catch (err) {
+            log?.warn("offboarding: cannot write session revocation markers", { err });
+        }
+        for (const [conversationId, seq] of r.notify) {
+            try {
+                await eventLog?.notify(conversationId, seq);
+            }
+            catch (err) {
+                log?.warn("offboarding: event notify failed", { conversationId, err });
+            }
+        }
+        for (const conversationId of r.queueConversations) {
+            try {
+                await eventLog?.publishChanged?.(conversationId, "queue");
+            }
+            catch (err) {
+                log?.warn("offboarding: queue change notify failed", { conversationId, err });
+            }
+        }
+        for (const run of r.runs)
+            await this.stopRun(run);
+        if (r.sandboxConversations.length > 0 && this.deps.sandboxes) {
+            try {
+                await this.deps.sandboxes.destroy(r.sandboxConversations);
+            }
+            catch (err) {
+                log?.warn("offboarding: cannot schedule sandbox destruction", {
+                    count: r.sandboxConversations.length,
+                    err,
+                });
+            }
+        }
+    }
+    /**
+     * 中止一个运行，顺序同会话中止接口：waiting → 直接取消等待并写终态；孤儿 → 直接写终态；
+     * 否则经 Redis 广播中止（运行所在副本收到后结束；尚未开始的运行开始时补查中止标记）。失败只记 warn。
+     * 不像会话中止那样随后起新一轮运行：离职者的待处理消息不再处理。
+     */
+    async stopRun(run) {
+        const ctl = this.deps.runs;
+        if (!ctl)
+            return;
+        try {
+            if (run.status === "waiting" &&
+                (await ctl.abortWaiting(run.conversationId, run.runId, null))) {
+                return;
+            }
+            if (await ctl.abortIfOrphaned(run.conversationId, run.runId, null))
+                return;
+            await ctl.requestAbort(run.runId, null);
+            // 广播中止的运行要等所在副本到达步骤边界才真正结束：广播成功后记标记，扫描在其有效期内不再重复广播
+            // （广播失败不记，下一轮扫描重试）
+            await this.deps.redis
+                ?.set(offboardAbortKey(run.runId), "1", "EX", OFFBOARD_ABORT_MARK_TTL_SECONDS)
+                .catch((err) => this.deps.log?.warn("offboarding: cannot mark abort", { err }));
+        }
+        catch (err) {
+            this.deps.log?.warn("offboarding: cannot stop run", { runId: run.runId, err });
+        }
+    }
+    /**
+     * 兜底扫描（维护队列每 10 分钟）：进行中、且发起人已不是该会话所属组织成员的运行 → 中止
+     * （提交后的中止没做成时，如进程崩溃）。按 `(runs.created_at, runs.id)` 键集分页翻完（每页 500 条，
+     * 至多 20 页）：经广播中止、尚未真正结束的运行仍是进行中，若只取前 500 条，超过 500 条卡住的运行会
+     * 一直占满这一页，后面的永远轮不到。已广播中止、仍带 `capk:offboard-abort:<runId>` 标记（30 分钟）的运行跳过，
+     * 不每轮重复广播；标记过期仍未结束的再处理一次。返回本次处理（未跳过）的运行数。
+     * 现任成员（含匿名访客这样的 guest 成员）发起的运行不受影响。
+     */
+    async sweep() {
+        const { db } = this.deps;
+        if (!db || !this.deps.runs)
+            return 0;
+        const batch = this.deps.sweepBatch ?? OFFBOARD_SWEEP_BATCH;
+        // 游标的时间用文本保存完整的微秒精度（JS Date 只有毫秒，会让同一行再被取到）
+        let after;
+        let total = 0;
+        for (let page = 0; page < OFFBOARD_SWEEP_MAX_PAGES; page++) {
+            const cursor = after;
+            const rows = await db
+                .selectFrom("runs")
+                .innerJoin("conversations", "conversations.id", "runs.conversation_id")
+                .select(["runs.id", "runs.conversation_id", "runs.status"])
+                .select(sql `runs.created_at::text`.as("created_at_text"))
+                .where("runs.status", "in", ACTIVE)
+                // a removed member's sub-agents run with their identity and credentials: stopped too
+                .where("conversations.kind", "in", ["chat", "subagent"])
+                .where(({ not, exists, selectFrom }) => not(exists(selectFrom("memberships")
+                .select(sql `1`.as("one"))
+                .whereRef("memberships.org_id", "=", "conversations.org_id")
+                .whereRef("memberships.account_id", "=", "runs.trigger_account_id"))))
+                .$if(cursor !== undefined, (q) => q.where(sql `(runs.created_at, runs.id) > (${cursor?.createdAt}::timestamptz, ${cursor?.id})`))
+                .orderBy("runs.created_at")
+                .orderBy("runs.id")
+                .limit(batch)
+                .execute();
+            for (const r of rows) {
+                if (await this.recentlyAborted(r.id))
+                    continue;
+                total++;
+                this.deps.log?.warn("offboard sweep: stopping run of a former member", { runId: r.id });
+                await this.stopRun({
+                    conversationId: r.conversation_id,
+                    runId: r.id,
+                    status: r.status,
+                });
+            }
+            const last = rows[rows.length - 1];
+            if (rows.length < batch || !last)
+                break;
+            after = { createdAt: last.created_at_text, id: last.id };
+        }
+        return total;
+    }
+    async recentlyAborted(runId) {
+        try {
+            return (await this.deps.redis?.exists(offboardAbortKey(runId))) === 1;
+        }
+        catch {
+            return false;
+        }
+    }
+}

package/dist/orgs/org-lock.d.ts

@@ -0,0 +1,32 @@
+import type { Transaction } from "kysely";
+import type { KernelDatabase } from "../db/kernel-schema.js";
+import { type OrgAction, type OrgRole } from "./roles.js";
+type Trx = Transaction<KernelDatabase>;
+/** 被锁组织的元数据（审计记录改动前的值用）。 */
+export interface LockedOrg {
+    slug: string;
+    name: string;
+}
+/**
+ * `SELECT … FROM capybara.orgs WHERE id = $1 AND deleted_at IS NULL FOR NO KEY UPDATE`：锁住组织行，
+ * 串行化同一组织的成员 / 邀请 / 令牌 / 配置写操作。组织不存在或已软删除时返回 undefined。
+ *
+ * NO KEY UPDATE, not UPDATE: the holders still exclude each other (and `FOR SHARE` readers), but a
+ * foreign key check against the org row (`FOR KEY SHARE`, taken by every insert of a row that
+ * references the org, and by an update of a row the same transaction already wrote) is not blocked.
+ * With FOR UPDATE, offboarding (org row, then the member's conversations) deadlocked with an event
+ * log append (a conversation row, then the org foreign key check).
+ */
+export declare function tryLockOrg(t: Trx, orgId: string): Promise<LockedOrg | undefined>;
+/** 同 `tryLockOrg`，组织不存在或已软删除 → `org.not_found`。 */
+export declare function lockOrg(t: Trx, orgId: string): Promise<LockedOrg>;
+/**
+ * 依赖角色的组织写操作的执行期复核（spec 3.6 R5）：锁组织行，并在锁内实时重读发起人的角色。
+ * 组织不存在或已软删除 → `org.not_found`；发起人不是成员或角色不足以执行 `action` → `forbidden`。
+ * 服务只接收发起人账号 id，不接收调用方传入的角色。
+ */
+export declare function lockOrgAndAuthorize(t: Trx, orgId: string, actorAccountId: string, action: OrgAction): Promise<{
+    org: LockedOrg;
+    role: OrgRole;
+}>;
+export {};

package/dist/orgs/org-lock.js

@@ -0,0 +1,46 @@
+import { ApiError } from "../errors.js";
+import { can } from "./roles.js";
+/**
+ * `SELECT … FROM capybara.orgs WHERE id = $1 AND deleted_at IS NULL FOR NO KEY UPDATE`：锁住组织行，
+ * 串行化同一组织的成员 / 邀请 / 令牌 / 配置写操作。组织不存在或已软删除时返回 undefined。
+ *
+ * NO KEY UPDATE, not UPDATE: the holders still exclude each other (and `FOR SHARE` readers), but a
+ * foreign key check against the org row (`FOR KEY SHARE`, taken by every insert of a row that
+ * references the org, and by an update of a row the same transaction already wrote) is not blocked.
+ * With FOR UPDATE, offboarding (org row, then the member's conversations) deadlocked with an event
+ * log append (a conversation row, then the org foreign key check).
+ */
+export async function tryLockOrg(t, orgId) {
+    return t
+        .selectFrom("orgs")
+        .select(["slug", "name"])
+        .where("id", "=", orgId)
+        .where("deleted_at", "is", null)
+        .forNoKeyUpdate()
+        .executeTakeFirst();
+}
+/** 同 `tryLockOrg`，组织不存在或已软删除 → `org.not_found`。 */
+export async function lockOrg(t, orgId) {
+    const org = await tryLockOrg(t, orgId);
+    if (!org)
+        throw new ApiError("org.not_found", "Organization not found");
+    return org;
+}
+/**
+ * 依赖角色的组织写操作的执行期复核（spec 3.6 R5）：锁组织行，并在锁内实时重读发起人的角色。
+ * 组织不存在或已软删除 → `org.not_found`；发起人不是成员或角色不足以执行 `action` → `forbidden`。
+ * 服务只接收发起人账号 id，不接收调用方传入的角色。
+ */
+export async function lockOrgAndAuthorize(t, orgId, actorAccountId, action) {
+    const org = await lockOrg(t, orgId);
+    const m = await t
+        .selectFrom("memberships")
+        .select("role")
+        .where("org_id", "=", orgId)
+        .where("account_id", "=", actorAccountId)
+        .executeTakeFirst();
+    if (!m || !can(m.role, action)) {
+        throw new ApiError("forbidden", "Insufficient organization role");
+    }
+    return { org, role: m.role };
+}

package/dist/orgs/org.guard.d.ts

@@ -0,0 +1,35 @@
+import { type CanActivate, type ExecutionContext } from "@nestjs/common";
+import { Reflector } from "@nestjs/core";
+import type { KernelDb } from "../db/kernel-schema.js";
+import { type OrgAction as Action, type OrgRole } from "./roles.js";
+/** OrgGuard 放在请求上的组织上下文。 */
+export interface OrgContext {
+    orgId: string;
+    role: OrgRole;
+}
+declare module "fastify" {
+    interface FastifyRequest {
+        /** 由 OrgGuard 设置（仅 `@OrgAction` 路由）。 */
+        org?: OrgContext;
+    }
+}
+export declare const ORG_ACTION_KEY = "capybara:org:action";
+/**
+ * 组织级路由：声明所需动作，读路径参数 `:orgId`，由 OrgGuard（在全局 AuthGuard 之后）判定。
+ * 隐含 `@AllowService()`：服务令牌能到达 OrgGuard，再由它核对所属组织与 HUMAN_ONLY。
+ */
+export declare function OrgAction(action: Action): MethodDecorator & ClassDecorator;
+/** 参数装饰器：取 OrgGuard 放在 `req.org` 上的 `{ orgId, role }`。 */
+export declare const CurrentOrg: () => ParameterDecorator;
+/**
+ * 组织守卫：每个请求实时从 PG 读组织与成员角色（不缓存）。
+ * - 组织不存在、已软删除、或调用者不是成员 → 404 `org.not_found`（不泄露组织是否存在）。
+ * - user principal 的角色取 memberships；service principal 只认令牌所属组织，角色取令牌上的 role。
+ * - HUMAN_ONLY 动作遇到 service principal → 403 `forbidden`；角色不足 → 403 `forbidden`。
+ */
+export declare class OrgGuard implements CanActivate {
+    private readonly reflector;
+    private readonly db;
+    constructor(reflector: Reflector, db: KernelDb);
+    canActivate(ctx: ExecutionContext): Promise<boolean>;
+}

package/dist/orgs/org.guard.js

@@ -0,0 +1,95 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { applyDecorators, createParamDecorator, Inject, Injectable, SetMetadata, UseGuards, } from "@nestjs/common";
+import { Reflector } from "@nestjs/core";
+import { ApiError } from "../errors.js";
+import { KERNEL_DB } from "../http/tokens.js";
+import { AllowService } from "../identity/principal.js";
+import { can, HUMAN_ONLY } from "./roles.js";
+export const ORG_ACTION_KEY = "capybara:org:action";
+/**
+ * 组织级路由：声明所需动作，读路径参数 `:orgId`，由 OrgGuard（在全局 AuthGuard 之后）判定。
+ * 隐含 `@AllowService()`：服务令牌能到达 OrgGuard，再由它核对所属组织与 HUMAN_ONLY。
+ */
+export function OrgAction(action) {
+    return applyDecorators(SetMetadata(ORG_ACTION_KEY, action), AllowService(), UseGuards(OrgGuard));
+}
+/** 参数装饰器：取 OrgGuard 放在 `req.org` 上的 `{ orgId, role }`。 */
+export const CurrentOrg = createParamDecorator((_data, ctx) => ctx.switchToHttp().getRequest().org);
+const notFound = () => new ApiError("org.not_found", "Organization not found");
+/**
+ * 组织守卫：每个请求实时从 PG 读组织与成员角色（不缓存）。
+ * - 组织不存在、已软删除、或调用者不是成员 → 404 `org.not_found`（不泄露组织是否存在）。
+ * - user principal 的角色取 memberships；service principal 只认令牌所属组织，角色取令牌上的 role。
+ * - HUMAN_ONLY 动作遇到 service principal → 403 `forbidden`；角色不足 → 403 `forbidden`。
+ */
+let OrgGuard = class OrgGuard {
+    reflector;
+    db;
+    constructor(reflector, db) {
+        this.reflector = reflector;
+        this.db = db;
+    }
+    async canActivate(ctx) {
+        const action = this.reflector.getAllAndOverride(ORG_ACTION_KEY, [
+            ctx.getHandler(),
+            ctx.getClass(),
+        ]);
+        if (!action)
+            throw new Error("OrgGuard: route has no @OrgAction()");
+        const req = ctx.switchToHttp().getRequest();
+        const p = req.principal;
+        if (!p)
+            throw new Error("OrgGuard: no principal; is this route wrongly marked @Public()?");
+        const orgId = req.params.orgId;
+        if (!orgId)
+            throw new Error("OrgGuard: route has no :orgId parameter");
+        let role;
+        if (p.kind === "service") {
+            if (p.orgId !== orgId)
+                throw notFound();
+            const live = await this.db
+                .selectFrom("orgs")
+                .select("id")
+                .where("id", "=", orgId)
+                .where("deleted_at", "is", null)
+                .executeTakeFirst();
+            if (!live)
+                throw notFound();
+            if (HUMAN_ONLY.has(action)) {
+                throw new ApiError("forbidden", "Service tokens cannot perform this action");
+            }
+            role = p.role;
+        }
+        else {
+            const m = await this.db
+                .selectFrom("memberships")
+                .innerJoin("orgs", "orgs.id", "memberships.org_id")
+                .select("memberships.role")
+                .where("memberships.org_id", "=", orgId)
+                .where("memberships.account_id", "=", p.account.id)
+                .where("orgs.deleted_at", "is", null)
+                .executeTakeFirst();
+            if (!m)
+                throw notFound();
+            role = m.role;
+        }
+        if (!can(role, action))
+            throw new ApiError("forbidden", "Insufficient organization role");
+        req.org = { orgId, role };
+        return true;
+    }
+};
+OrgGuard = __decorate([
+    Injectable(),
+    __param(0, Inject(Reflector)),
+    __param(1, Inject(KERNEL_DB))
+], OrgGuard);
+export { OrgGuard };