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

package/dist/orgs/invitations.controller.js

@@ -0,0 +1,137 @@
+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 { Body, Controller, Delete, Get, HttpCode, Inject, Param, Post, Req, Res, } from "@nestjs/common";
+import { z } from "zod";
+import { ApiError } from "../errors.js";
+import { INVITATIONS, KERNEL_CONFIG, RATE_LIMITER, SESSIONS } from "../http/tokens.js";
+import { ZodPipe } from "../http/zod.pipe.js";
+import { clientMeta } from "../identity/auth.controller.js";
+import { setSessionCookies } from "../identity/cookies.js";
+import { CurrentPrincipal, Public, patTokenId, requireUser, } from "../identity/principal.js";
+import { INVITABLE_ROLES, MAX_INVITATION_HOURS, } from "./invitations.service.js";
+import { CurrentOrg, OrgAction } from "./org.guard.js";
+const CreateBody = z.object({
+    role: z.enum(INVITABLE_ROLES),
+    expiresInHours: z.number().int().min(1).max(MAX_INVITATION_HOURS).optional(),
+});
+const SignupBody = z.object({
+    login: z.string(),
+    password: z.string(),
+    displayName: z.string().min(1).max(100),
+});
+const signupPipe = new ZodPipe(SignupBody);
+/** 接受邀请的限流（scope `inv`）：同一令牌 10 次、同一客户端 IP 20 次 / 900s。 */
+const ACCEPT_LIMIT_PER_TOKEN = 10;
+const ACCEPT_LIMIT_PER_IP = 20;
+/** 组织邀请：组织内管理（`/api/v1/orgs/:orgId/invitations`）与凭令牌预览 / 接受（`/api/v1/invitations/:token`，公开）。 */
+let InvitationsController = class InvitationsController {
+    invitations;
+    sessions;
+    config;
+    limiter;
+    constructor(invitations, sessions, config, limiter) {
+        this.invitations = invitations;
+        this.sessions = sessions;
+        this.config = config;
+        this.limiter = limiter;
+    }
+    /** 令牌只在此返回一次。 */
+    async create(principal, org, body) {
+        const p = requireUser(principal);
+        return this.invitations.create(org.orgId, body, p.account.id, patTokenId(p));
+    }
+    async list(org) {
+        return { invitations: await this.invitations.list(org.orgId) };
+    }
+    async revoke(principal, org, id) {
+        const p = requireUser(principal);
+        await this.invitations.revoke(org.orgId, id, p.account.id, patTokenId(p));
+    }
+    /** 公开预览：只给组织 id / 名称、角色与过期时间。 */
+    async preview(token) {
+        return this.invitations.preview(token);
+    }
+    /**
+     * 接受邀请：已登录的 user principal 直接加入（body 可为空）；未登录则 body 必须是
+     * `{ login, password, displayName }`，注册成功后创建会话并设 Cookie；service principal → `forbidden`。
+     * 每次尝试先占用限流额度（scope `inv`：按令牌与客户端 IP），防止猜令牌、探测登录名与用 scrypt 拖垮服务；
+     * 超限 → 429 `auth.rate_limited`，成功后退还。
+     */
+    async accept(token, principal, body, req, reply) {
+        if (principal?.kind === "service") {
+            throw new ApiError("forbidden", "Service tokens cannot accept invitations");
+        }
+        const meta = clientMeta(req);
+        const rl = await this.limiter.reserveScoped("inv", token, meta.ip, ACCEPT_LIMIT_PER_TOKEN, ACCEPT_LIMIT_PER_IP);
+        if (!rl.allowed) {
+            reply.header("retry-after", String(rl.retryAfterSeconds));
+            throw new ApiError("auth.rate_limited", "Too many invitation attempts; try again later");
+        }
+        let result;
+        if (principal) {
+            result = await this.invitations.accept(token, { accountId: principal.account.id });
+            await this.limiter.succeededScoped("inv", token, meta.ip);
+        }
+        else {
+            const signup = signupPipe.transform(body);
+            // 新账号、成员关系与会话行在同一事务里写入；Cookie 在提交之后才设置
+            const { extra: session, ...rest } = await this.invitations.accept(token, { signup }, (t, account) => this.sessions.create(account.id, meta, t));
+            if (!session)
+                throw new Error("signup completed without a session");
+            result = rest;
+            await this.limiter.succeededScoped("inv", token, meta.ip);
+            setSessionCookies(reply, session, this.config());
+        }
+        return result;
+    }
+};
+__decorate([
+    Post("orgs/:orgId/invitations"),
+    OrgAction("org.invitations.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Body(new ZodPipe(CreateBody)))
+], InvitationsController.prototype, "create", null);
+__decorate([
+    Get("orgs/:orgId/invitations"),
+    OrgAction("org.invitations.manage"),
+    __param(0, CurrentOrg())
+], InvitationsController.prototype, "list", null);
+__decorate([
+    Delete("orgs/:orgId/invitations/:id"),
+    OrgAction("org.invitations.manage"),
+    HttpCode(204),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("id"))
+], InvitationsController.prototype, "revoke", null);
+__decorate([
+    Get("invitations/:token"),
+    Public(),
+    __param(0, Param("token"))
+], InvitationsController.prototype, "preview", null);
+__decorate([
+    Post("invitations/:token/accept"),
+    Public(),
+    HttpCode(200),
+    __param(0, Param("token")),
+    __param(1, CurrentPrincipal()),
+    __param(2, Body()),
+    __param(3, Req()),
+    __param(4, Res({ passthrough: true }))
+], InvitationsController.prototype, "accept", null);
+InvitationsController = __decorate([
+    Controller("api/v1"),
+    __param(0, Inject(INVITATIONS)),
+    __param(1, Inject(SESSIONS)),
+    __param(2, Inject(KERNEL_CONFIG)),
+    __param(3, Inject(RATE_LIMITER))
+], InvitationsController);
+export { InvitationsController };

package/dist/orgs/invitations.service.d.ts

@@ -0,0 +1,80 @@
+import { type Transaction } from "kysely";
+import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
+import type { Account, AccountsService } from "../identity/accounts.js";
+import type { MembersService } from "./members.service.js";
+import { type OrgRole } from "./roles.js";
+type Trx = Transaction<KernelDatabase>;
+/** 可邀请的角色（owner 只能经转让获得）。 */
+export declare const INVITABLE_ROLES: readonly ["admin", "member", "guest"];
+export type InvitableRole = (typeof INVITABLE_ROLES)[number];
+export declare const DEFAULT_INVITATION_HOURS = 168;
+export declare const MAX_INVITATION_HOURS = 720;
+export type Invitation = {
+    id: string;
+    orgId: string;
+    role: InvitableRole;
+    createdBy: string;
+    createdAt: Date;
+    expiresAt: Date;
+    acceptedAt: Date | null;
+    revokedAt: Date | null;
+};
+export type InvitationStatus = "pending" | "accepted" | "expired" | "revoked";
+export type AcceptAs = {
+    accountId: string;
+} | {
+    signup: {
+        login: string;
+        password: string;
+        displayName: string;
+    };
+};
+/**
+ * 组织邀请。令牌 `cap_inv_` + 32 字节 base64url，库里只存 SHA-256（按 hash 在 SQL 里查找）。
+ * 写操作（create / revoke）与成员服务一样先锁组织行，并在锁内实时重读发起人角色（只接收账号 id，不接收角色）。
+ * 加锁顺序统一为「组织行 → 邀请行」，accept 也先锁组织行，避免与 revoke 死锁。框架无关，由调用方注入依赖。
+ */
+export declare class InvitationsService {
+    private readonly db;
+    private readonly accounts;
+    private readonly members;
+    constructor(db: KernelDb, accounts: AccountsService, members: MembersService);
+    create(orgId: string, input: {
+        role: InvitableRole;
+        expiresInHours?: number | undefined;
+    }, actorAccountId: string, actorTokenId?: string): Promise<{
+        invitation: Invitation;
+        token: string;
+    }>;
+    list(orgId: string): Promise<(Invitation & {
+        status: InvitationStatus;
+    })[]>;
+    /** 撤销；不属于该组织 → `invitation.invalid`；已接受 → `invitation.used`；已撤销则无操作。 */
+    revoke(orgId: string, id: string, actorAccountId: string, actorTokenId?: string): Promise<void>;
+    preview(token: string): Promise<{
+        org: {
+            id: string;
+            name: string;
+        };
+        role: InvitableRole;
+        expiresAt: Date;
+    }>;
+    /**
+     * 接受邀请，单个事务：按 hash 读邀请并分类错误 →（signup 时建账号）→ 锁组织行
+     * → 条件 UPDATE 占用邀请（0 行则重新分类，并发的后到者得到 `invitation.used`）→ 加入成员（`members.add` 检查已是成员 → `member.already_exists`，整体回滚含邀请占用）。任何一步失败整体回滚。
+     * signup 时先在事务外分类一次（无效令牌不白跑 scrypt），再在 BEGIN 之前算好密码哈希，
+     * 事务内只有读写，连接不会在 scrypt 期间处于 idle in transaction。
+     */
+    accept<T = undefined>(token: string, who: AcceptAs, inTx?: (t: Trx, account: Account) => Promise<T>): Promise<{
+        account: Account;
+        orgId: string;
+        role: OrgRole;
+        extra: T | undefined;
+    }>;
+    /**
+     * 按令牌 hash 读邀请并分类：不存在、已撤销或组织已软删除 → `invitation.invalid`；
+     * 已接受 → `invitation.used`；已过期 → `invitation.expired`。过期按数据库时间判定。
+     */
+    private classify;
+}
+export {};

package/dist/orgs/invitations.service.js

@@ -0,0 +1,217 @@
+import { randomBytes, randomUUID } from "node:crypto";
+import { sql } from "kysely";
+import { ApiError } from "../errors.js";
+import { audit } from "../identity/audit.js";
+import { sha256Hex } from "../identity/hash.js";
+import { lockOrgAndAuthorize, tryLockOrg } from "./org-lock.js";
+import { roleAtLeast } from "./roles.js";
+/** 可邀请的角色（owner 只能经转让获得）。 */
+export const INVITABLE_ROLES = ["admin", "member", "guest"];
+export const DEFAULT_INVITATION_HOURS = 168;
+export const MAX_INVITATION_HOURS = 720;
+const TOKEN_PREFIX = "cap_inv_";
+function toInvitation(r) {
+    return {
+        id: r.id,
+        orgId: r.org_id,
+        role: r.role,
+        createdBy: r.created_by,
+        createdAt: r.created_at,
+        expiresAt: r.expires_at,
+        acceptedAt: r.accepted_at,
+        revokedAt: r.revoked_at,
+    };
+}
+const invalid = () => new ApiError("invitation.invalid", "Invitation is invalid");
+const forbidden = () => new ApiError("forbidden", "Insufficient organization role");
+/**
+ * 组织邀请。令牌 `cap_inv_` + 32 字节 base64url，库里只存 SHA-256（按 hash 在 SQL 里查找）。
+ * 写操作（create / revoke）与成员服务一样先锁组织行，并在锁内实时重读发起人角色（只接收账号 id，不接收角色）。
+ * 加锁顺序统一为「组织行 → 邀请行」，accept 也先锁组织行，避免与 revoke 死锁。框架无关，由调用方注入依赖。
+ */
+export class InvitationsService {
+    db;
+    accounts;
+    members;
+    constructor(db, accounts, members) {
+        this.db = db;
+        this.accounts = accounts;
+        this.members = members;
+    }
+    async create(orgId, input, actorAccountId, actorTokenId) {
+        if (!INVITABLE_ROLES.includes(input.role)) {
+            throw new ApiError("validation_failed", "Role cannot be invited");
+        }
+        const hours = input.expiresInHours ?? DEFAULT_INVITATION_HOURS;
+        if (!Number.isInteger(hours) || hours < 1 || hours > MAX_INVITATION_HOURS) {
+            throw new ApiError("validation_failed", `expiresInHours must be an integer between 1 and ${MAX_INVITATION_HOURS}`);
+        }
+        const token = TOKEN_PREFIX + randomBytes(32).toString("base64url");
+        return this.db.transaction().execute(async (t) => {
+            const { role: actorRole } = await lockOrgAndAuthorize(t, orgId, actorAccountId, "org.invitations.manage");
+            if (!roleAtLeast(actorRole, input.role))
+                throw forbidden();
+            const row = await t
+                .insertInto("invitations")
+                .values({
+                id: randomUUID(),
+                org_id: orgId,
+                role: input.role,
+                token_hash: sha256Hex(token),
+                created_by: actorAccountId,
+                expires_at: sql `now() + make_interval(hours => ${hours})`,
+            })
+                .returningAll()
+                .executeTakeFirstOrThrow();
+            await audit(t, {
+                actorAccountId,
+                ...(actorTokenId !== undefined && { actorTokenId }),
+                orgId,
+                action: "org.invitation.created",
+                target: row.id,
+                detail: { role: input.role, expiresAt: row.expires_at.toISOString() },
+            });
+            return { invitation: toInvitation(row), token };
+        });
+    }
+    async list(orgId) {
+        const rows = await this.db
+            .selectFrom("invitations")
+            .selectAll()
+            .select(sql `expires_at <= now()`.as("expired"))
+            .where("org_id", "=", orgId)
+            .orderBy("created_at")
+            .orderBy("id")
+            .execute();
+        return rows.map(({ expired, ...r }) => {
+            const status = r.revoked_at
+                ? "revoked"
+                : r.accepted_at
+                    ? "accepted"
+                    : expired
+                        ? "expired"
+                        : "pending";
+            return { ...toInvitation(r), status };
+        });
+    }
+    /** 撤销；不属于该组织 → `invitation.invalid`；已接受 → `invitation.used`；已撤销则无操作。 */
+    async revoke(orgId, id, actorAccountId, actorTokenId) {
+        await this.db.transaction().execute(async (t) => {
+            await lockOrgAndAuthorize(t, orgId, actorAccountId, "org.invitations.manage");
+            const row = await t
+                .selectFrom("invitations")
+                .selectAll()
+                .where("id", "=", id)
+                .where("org_id", "=", orgId)
+                .forUpdate()
+                .executeTakeFirst();
+            if (!row)
+                throw invalid();
+            if (row.accepted_at)
+                throw new ApiError("invitation.used", "Invitation was already used");
+            if (row.revoked_at)
+                return;
+            await t
+                .updateTable("invitations")
+                .set({ revoked_at: sql `now()` })
+                .where("id", "=", id)
+                .execute();
+            await audit(t, {
+                actorAccountId,
+                ...(actorTokenId !== undefined && { actorTokenId }),
+                orgId,
+                action: "org.invitation.revoked",
+                target: id,
+                detail: { role: row.role },
+            });
+        });
+    }
+    async preview(token) {
+        const r = await this.classify(this.db, token);
+        return { org: { id: r.org_id, name: r.org_name }, role: r.role, expiresAt: r.expires_at };
+    }
+    /**
+     * 接受邀请，单个事务：按 hash 读邀请并分类错误 →（signup 时建账号）→ 锁组织行
+     * → 条件 UPDATE 占用邀请（0 行则重新分类，并发的后到者得到 `invitation.used`）→ 加入成员（`members.add` 检查已是成员 → `member.already_exists`，整体回滚含邀请占用）。任何一步失败整体回滚。
+     * signup 时先在事务外分类一次（无效令牌不白跑 scrypt），再在 BEGIN 之前算好密码哈希，
+     * 事务内只有读写，连接不会在 scrypt 期间处于 idle in transaction。
+     */
+    async accept(token, who, inTx) {
+        let existing;
+        let passwordHash;
+        if ("accountId" in who) {
+            existing = await this.accounts.get(who.accountId);
+            if (!existing)
+                throw new ApiError("account.not_found", "Account not found");
+        }
+        else {
+            await this.classify(this.db, token);
+            passwordHash = await this.accounts.hashNewPassword(who.signup.password);
+        }
+        return this.db.transaction().execute(async (t) => {
+            const inv = await this.classify(t, token);
+            // 先建账号再锁组织行，缩短持锁时间；失败时随事务回滚，不残留账号
+            const account = existing ?? (await this.accounts.createLocal(signupOf(who), t, passwordHash));
+            if (!(await tryLockOrg(t, inv.org_id)))
+                throw invalid();
+            const taken = await t
+                .updateTable("invitations")
+                .set({ accepted_at: sql `now()`, accepted_by: account.id })
+                .where("id", "=", inv.id)
+                .where("accepted_at", "is", null)
+                .where("revoked_at", "is", null)
+                .where(sql `expires_at > now()`)
+                .returning("id")
+                .executeTakeFirst();
+            if (!taken) {
+                await this.classify(t, token);
+                throw new ApiError("invitation.used", "Invitation was already used");
+            }
+            await this.members.add(inv.org_id, account.id, inv.role, account.id, t);
+            await audit(t, {
+                actorAccountId: account.id,
+                orgId: inv.org_id,
+                action: "org.invitation.accepted",
+                target: inv.id,
+                detail: { role: inv.role, signup: "signup" in who },
+            });
+            // 凭邀请注册时在同一事务里建会话：失败整体回滚，不残留没有会话的新账号
+            const extra = inTx ? await inTx(t, account) : undefined;
+            return { account, orgId: inv.org_id, role: inv.role, extra };
+        });
+    }
+    /**
+     * 按令牌 hash 读邀请并分类：不存在、已撤销或组织已软删除 → `invitation.invalid`；
+     * 已接受 → `invitation.used`；已过期 → `invitation.expired`。过期按数据库时间判定。
+     */
+    async classify(db, token) {
+        const r = await db
+            .selectFrom("invitations")
+            .innerJoin("orgs", "orgs.id", "invitations.org_id")
+            .select([
+            "invitations.id",
+            "invitations.org_id",
+            "invitations.role",
+            "invitations.expires_at",
+            "invitations.accepted_at",
+            "invitations.revoked_at",
+            "orgs.name as org_name",
+            "orgs.deleted_at as org_deleted_at",
+        ])
+            .select(sql `invitations.expires_at <= now()`.as("expired"))
+            .where("invitations.token_hash", "=", sha256Hex(token))
+            .executeTakeFirst();
+        if (!r || r.revoked_at || r.org_deleted_at)
+            throw invalid();
+        if (r.accepted_at)
+            throw new ApiError("invitation.used", "Invitation was already used");
+        if (r.expired)
+            throw new ApiError("invitation.expired", "Invitation has expired");
+        return r;
+    }
+}
+function signupOf(who) {
+    if (!("signup" in who))
+        throw new Error("unreachable");
+    return who.signup;
+}

package/dist/orgs/members.service.d.ts

@@ -0,0 +1,63 @@
+import type { Transaction } from "kysely";
+import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
+import type { Account } from "../identity/accounts.js";
+import type { Offboarding } from "./offboarding.js";
+import type { OrgRole } from "./roles.js";
+type Trx = Transaction<KernelDatabase>;
+export interface Member {
+    account: Pick<Account, "id" | "displayName" | "email">;
+    role: OrgRole;
+    joinedAt: Date;
+    /** 该组织的匿名访客（渠道连接的匿名策略用）：不能改角色、移出、转让所有权或指派为 agent 负责人。 */
+    anonymous: boolean;
+}
+/**
+ * 账号是不是某个组织的匿名访客（`org_anonymous_accounts`）。匿名访客没有登录方式，只能以 guest 身份
+ * 代表 IM 里未绑定的人：不能被授予别的角色、成为 owner、指派为 agent 负责人、加入别的组织或被移出。
+ */
+export declare function isAnonymousGuest(db: KernelDb | Trx, accountId: string): Promise<boolean>;
+/** 目标是匿名访客 → `409 member.anonymous_guest`。 */
+export declare function rejectAnonymousGuest(db: KernelDb | Trx, accountId: string): Promise<void>;
+/**
+ * 成员服务。发起人只传账号 id，角色由服务在组织行锁内实时读取，调用方无法传入过期角色。所有写操作在事务内先 `SELECT … FROM orgs WHERE id = $1 FOR NO KEY UPDATE`，
+ * 把同一组织的成员变更串行化（多副本下两个 owner 并发互相降级也恰好剩一个 owner）。
+ * 框架无关，由调用方注入 db。
+ */
+export declare class MembersService {
+    private readonly db;
+    private readonly offboarding;
+    /** `offboarding`：移出与离开走的离职处理（内核用 `Kernel.identity.offboarding`）。 */
+    constructor(db: KernelDb, offboarding: Offboarding);
+    list(orgId: string): Promise<Member[]>;
+    /**
+     * 加入成员（邀请接受等，手动加入的唯一入口）；已是成员 → `member.already_exists`；匿名访客 → `member.anonymous_guest`。
+     * 同一事务删除此人在该组织的通讯录排除（Ruling A20：手动重新加入后，通讯录同步恢复照常管理此人）。
+     * `actorAccountId` 仅用于审计。
+     */
+    add(orgId: string, accountId: string, role: OrgRole, actorAccountId: string, trx?: Trx): Promise<void>;
+    /**
+     * 改角色：授予或撤销 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`。
+     */
+    changeRole(orgId: string, targetId: string, role: OrgRole, actorAccountId: string, actorTokenId?: string): Promise<void>;
+    /**
+     * 移出成员：权限规则同 changeRole（移除 owner 须发起人是 owner）；移除最后一个 owner → `org.last_owner`。
+     * 走离职处理（{@link Offboarding.offboard}，原因 `removed`），与之同一事务；提交后写吊销标记、发布事件。
+     * 匿名访客不能移出（`member.anonymous_guest`；不再需要匿名访问时把渠道连接改回绑定策略）。
+     */
+    remove(orgId: string, targetId: string, actorAccountId: string, actorTokenId?: string): Promise<void>;
+    /** 主动离开：走离职处理（原因 `left`）；最后一个 owner → `org.last_owner`。 */
+    leave(orgId: string, accountId: string, actorTokenId?: string): Promise<void>;
+    /**
+     * 转让所有权：from 必须是 owner（`org.owner_required`）；to 必须是成员（`member.not_found`）且不是匿名访客
+     * （`member.anonymous_guest`）；to → owner、from → admin。
+     */
+    transferOwnership(orgId: string, fromAccountId: string, toAccountId: string, actorTokenId?: string): Promise<void>;
+    private roleIn;
+    private requireMember;
+    private setRole;
+    private assertHasOwner;
+}
+export {};