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

package/dist/identity/enterprise-admin.js

@@ -0,0 +1,27 @@
+import { sql } from "kysely";
+import { ApiError } from "../errors.js";
+/**
+ * 在调用方事务内取 `capybara.enterprise_admins` 咨询锁（事务结束释放），串行化所有企业管理员写操作
+ * （撤销 / 停用 / 新建管理员 / 改部署设置 / CLI 的 `capybara admin grant|revoke`）。只加锁、不鉴权：
+ * 没有发起账号的调用方（CLI）用它；有发起账号的用 {@link lockEnterpriseAdminsAndAuthorize}。
+ */
+export async function lockEnterpriseAdmins(trx) {
+    await sql `SELECT pg_advisory_xact_lock(hashtext('capybara.enterprise_admins'))`.execute(trx);
+}
+/**
+ * 企业管理员写操作的执行期复核（spec 3.6 R5）：{@link lockEnterpriseAdmins} 后在锁内实时确认发起人仍是
+ * 活跃企业管理员，否则 `forbidden`。鉴权守卫在请求开头读到的身份可能已过期（另一个管理员刚撤销了他），
+ * 必须在锁内重读。
+ */
+export async function lockEnterpriseAdminsAndAuthorize(trx, actorAccountId) {
+    await lockEnterpriseAdmins(trx);
+    const actor = await trx
+        .selectFrom("accounts")
+        .select("id")
+        .where("id", "=", actorAccountId)
+        .where("is_enterprise_admin", "=", true)
+        .where("status", "=", "active")
+        .executeTakeFirst();
+    if (!actor)
+        throw new ApiError("forbidden", "Enterprise admin required");
+}

package/dist/identity/external.d.ts

@@ -0,0 +1,106 @@
+import type { ExternalIdentity } from "@capybara-hq/plugin-sdk";
+import { type Transaction } from "kysely";
+import type { KernelConfig } from "../config/schema.js";
+import type { KernelDatabase, KernelDb, LinkedVia } from "../db/kernel-schema.js";
+type Trx = Transaction<KernelDatabase>;
+export type { LinkedVia };
+/**
+ * 第三方登录拒绝了这个身份（Ruling A18）：身份行经 IM 绑定链接建立，而请求没有带着同一账号的会话。
+ * 登录页原因码 `sso.identity_not_verified`。
+ */
+export declare class IdentityNotVerified extends Error {
+    constructor();
+}
+/** {@link ExternalIdentities.resolve} 的选项。 */
+export interface ResolveOptions {
+    /** 只有第三方登录路径传 true（Ruling A9）。 */
+    allowMerge?: boolean;
+    /** 新建身份行时记下的建立方式：第三方登录 `sso`，通讯录同步 `directory`。已有的行不改。 */
+    linkedVia: "sso" | "directory";
+    /**
+     * 第三方登录路径：已有的身份行须可用于登录（见 {@link ExternalIdentities.resolve}）。
+     * `sessionAccountId` 为请求已带着的 Web 会话的账号（没有会话时省略）。
+     */
+    login?: {
+        sessionAccountId?: string;
+    };
+}
+/** 账号已绑定的一个外部身份（不含本地登录名）。 */
+export interface LinkedIdentity {
+    source: string;
+    externalId: string;
+    email: string | null;
+    emailVerified: boolean;
+    displayName: string | null;
+    avatarUrl: string | null;
+    /**
+     * 身份行是怎么建立的（Ruling A18）：`bind` 只能在 IM 里代表本人，要用于第三方登录须本人登录后完成一次该身份的
+     * 第三方登录（网页据此显示「验证」）；null 为 0019 之前的旧行（按 sso 处理）。
+     */
+    linkedVia: "bind" | "sso" | "directory" | "local" | null;
+    createdAt: Date;
+}
+/** 身份源键里的插件名（`source` 中 `:` 之前的部分）。 */
+export declare function identityPlugin(source: string): string;
+/**
+ * 外部身份：按 `(source, externalId)` 映射到账号（登录、渠道入站、通讯录共用同一个键）。
+ * 首次出现时按「受信任的身份源 + 两侧邮箱均已验证」合并到既有账号，否则新建账号（不建组织）。
+ * 同一身份的并发首次解析用事务级咨询锁串行化，只建一个账号。框架无关，由调用方注入依赖。
+ */
+export declare class ExternalIdentities {
+    private readonly db;
+    private readonly config;
+    constructor(db: KernelDb, config: () => {
+        auth: Pick<KernelConfig["auth"], "trustedIdentitySources">;
+    });
+    /** 该外部身份绑定的账号 id；未绑定返回 undefined。 */
+    findAccount(source: string, externalId: string, trx?: Trx): Promise<string | undefined>;
+    /**
+     * 解析外部身份到账号。已绑定 → 该账号（顺带刷新身份行上的邮箱与资料）；未绑定 → 合并或新建（见类说明），
+     * 新身份行记 `linked_via = opts.linkedVia`（合并也是 `sso`）。
+     * 合并只在 `opts.allowMerge` 时考虑（Ruling A9：只有第三方登录路径传 true；渠道入站、通讯录不传）。
+     * 第三方登录（`opts.login`，Ruling A18 / A23）：已有的身份行若经 IM 绑定建立（`bind`），只证明了某个网页登录者
+     * 点过绑定链接，不证明他控制该外部身份——此时只有请求已带着**同一账号**的会话（本人在已登录状态下完成第三方登录，
+     * 证明自己控制该身份）才放行，并把行升级为 `sso`（审计 `identity.verified`）；否则抛 {@link IdentityNotVerified}。
+     * 通讯录建立的行（`directory`）不论租户是否受信任都可直接登录：身份源登录本身就证明登录者控制该身份，
+     * 而通讯录身份总是指向为它新建的账号（信任只影响合并与 `email_verified`）。旧行（`linked_via` 为 null）按 `sso` 处理。
+     * 新建账号的 `email_verified` 只在身份源受信任且身份邮箱已验证时为 true——不受信任的身份源可以声称任意邮箱
+     * 「已验证」，不能让它建出的账号成为日后受信任登录的合并目标。
+     * 合并写审计 `identity.linked`，新建写 `account.created`。不判断账号状态，由调用方决定（如登录拒绝停用账号）。
+     * 传 `trx` 时在调用方事务内执行；与 `link` 取同一把咨询锁，兜底用 `ON CONFLICT DO NOTHING` 后回读，
+     * 不抛唯一约束冲突、不中止调用方事务。
+     */
+    resolve(identity: ExternalIdentity, trx: Trx | undefined, opts: ResolveOptions): Promise<{
+        accountId: string;
+        created: boolean;
+    }>;
+    /** 同一身份的 resolve / link 串行化（事务级咨询锁）。 */
+    private lockIdentity;
+    /** 身份源键（`<插件名>:<租户 id>`）是否在 `auth.trustedIdentitySources` 中：按完整键比较，信任按租户（Ruling A19）。 */
+    private trusted;
+    private findRow;
+    /** 第三方登录能否用这一行（见 {@link resolve}）：只有 `bind` 行需要同一账号的会话，放行时把行改为 `sso`。 */
+    private allowLogin;
+    private mustFind;
+    private refreshIdentity;
+    /**
+     * 可合并的既有账号：身份源键在 `auth.trustedIdentitySources` 中、身份邮箱已验证，
+     * 且恰好有一个邮箱已验证、邮箱相同（不区分大小写）的账号；否则 undefined（多个候选时不猜，新建）。
+     */
+    private mergeTarget;
+    /** 插入身份行；已存在（主键冲突）时什么都不做并返回 false。 */
+    private insertIdentity;
+    /**
+     * 把外部身份绑定到账号（IM 里点绑定链接等）：已绑定本人 → 刷新资料，幂等（不改 `linked_via`）；
+     * 已绑定他人 → `409 identity.taken`。新行记 `linked_via = bind`：这样绑定的身份只能在 IM 里代表此人，
+     * 不能直接用于第三方登录（Ruling A18）。与 `resolve` 取同一把咨询锁。新绑定写审计 `identity.linked`。
+     */
+    link(accountId: string, identity: ExternalIdentity, trx?: Trx): Promise<void>;
+    /**
+     * 解除本人的一个外部身份（本地登录名不可解除）；不存在或不属于本人 → `identity.not_found`；
+     * 账号没有本地密码且这是最后一个外部身份 → `409 identity.last_login_method`。审计 `identity.unlinked`。
+     */
+    unlink(accountId: string, source: string, externalId: string): Promise<void>;
+    /** 账号绑定的外部身份（不含本地登录名），按绑定时间升序。 */
+    listForAccount(accountId: string): Promise<LinkedIdentity[]>;
+}

package/dist/identity/external.js

@@ -0,0 +1,337 @@
+import { randomUUID } from "node:crypto";
+import { sql } from "kysely";
+import { ApiError } from "../errors.js";
+import { audit } from "./audit.js";
+/** `<插件名>:<租户 id>`；插件名同清单规则，租户 id 为非空、不含空白的串。 */
+const SOURCE_RE = /^([a-z0-9][a-z0-9._-]{0,213}):(\S{1,256})$/;
+const MAX_EXTERNAL_ID = 256;
+const MAX_DISPLAY_NAME = 200;
+const MAX_EMAIL = 320;
+/**
+ * 第三方登录拒绝了这个身份（Ruling A18）：身份行经 IM 绑定链接建立，而请求没有带着同一账号的会话。
+ * 登录页原因码 `sso.identity_not_verified`。
+ */
+export class IdentityNotVerified extends Error {
+    constructor() {
+        super("external identity is not verified for sign-in");
+        this.name = "IdentityNotVerified";
+    }
+}
+/** 身份源键里的插件名（`source` 中 `:` 之前的部分）。 */
+export function identityPlugin(source) {
+    const i = source.indexOf(":");
+    return i < 0 ? source : source.slice(0, i);
+}
+const invalid = (message) => new ApiError("validation_failed", "Invalid external identity", [{ path: "identity", message }]);
+/** 校验插件交来的外部身份（键的格式、长度），返回规范化后的副本。 */
+function normalize(identity) {
+    const m = SOURCE_RE.exec(identity.source);
+    if (!m || m[1] === "local") {
+        throw invalid('source must be "<plugin>:<tenant>"');
+    }
+    // 身份源键的租户必须就是身份的租户（Ruling A19）：信任按租户判断，不能让键与租户各说各的
+    if (identity.tenantId !== m[2]) {
+        throw invalid("source tenant must equal tenantId");
+    }
+    if (typeof identity.externalId !== "string" ||
+        identity.externalId.length === 0 ||
+        identity.externalId.length > MAX_EXTERNAL_ID) {
+        throw invalid(`externalId must be 1-${MAX_EXTERNAL_ID} characters`);
+    }
+    const email = typeof identity.email === "string" && identity.email.length > 0
+        ? identity.email.trim().slice(0, MAX_EMAIL)
+        : undefined;
+    const displayName = (typeof identity.displayName === "string" ? identity.displayName.trim() : "").slice(0, MAX_DISPLAY_NAME) || identity.externalId.slice(0, MAX_DISPLAY_NAME);
+    return {
+        source: identity.source,
+        externalId: identity.externalId,
+        tenantId: identity.tenantId,
+        ...(email !== undefined && { email }),
+        emailVerified: email !== undefined && identity.emailVerified === true,
+        displayName,
+        ...(typeof identity.avatarUrl === "string" && { avatarUrl: identity.avatarUrl.slice(0, 2000) }),
+    };
+}
+const profileOf = (i) => JSON.stringify({
+    tenantId: i.tenantId,
+    displayName: i.displayName,
+    ...(i.avatarUrl !== undefined && { avatarUrl: i.avatarUrl }),
+});
+/**
+ * 外部身份：按 `(source, externalId)` 映射到账号（登录、渠道入站、通讯录共用同一个键）。
+ * 首次出现时按「受信任的身份源 + 两侧邮箱均已验证」合并到既有账号，否则新建账号（不建组织）。
+ * 同一身份的并发首次解析用事务级咨询锁串行化，只建一个账号。框架无关，由调用方注入依赖。
+ */
+export class ExternalIdentities {
+    db;
+    config;
+    constructor(db, config) {
+        this.db = db;
+        this.config = config;
+    }
+    /** 该外部身份绑定的账号 id；未绑定返回 undefined。 */
+    async findAccount(source, externalId, trx) {
+        const row = await (trx ?? this.db)
+            .selectFrom("identities")
+            .select("account_id")
+            .where("source", "=", source)
+            .where("external_id", "=", externalId)
+            .executeTakeFirst();
+        return row?.account_id;
+    }
+    /**
+     * 解析外部身份到账号。已绑定 → 该账号（顺带刷新身份行上的邮箱与资料）；未绑定 → 合并或新建（见类说明），
+     * 新身份行记 `linked_via = opts.linkedVia`（合并也是 `sso`）。
+     * 合并只在 `opts.allowMerge` 时考虑（Ruling A9：只有第三方登录路径传 true；渠道入站、通讯录不传）。
+     * 第三方登录（`opts.login`，Ruling A18 / A23）：已有的身份行若经 IM 绑定建立（`bind`），只证明了某个网页登录者
+     * 点过绑定链接，不证明他控制该外部身份——此时只有请求已带着**同一账号**的会话（本人在已登录状态下完成第三方登录，
+     * 证明自己控制该身份）才放行，并把行升级为 `sso`（审计 `identity.verified`）；否则抛 {@link IdentityNotVerified}。
+     * 通讯录建立的行（`directory`）不论租户是否受信任都可直接登录：身份源登录本身就证明登录者控制该身份，
+     * 而通讯录身份总是指向为它新建的账号（信任只影响合并与 `email_verified`）。旧行（`linked_via` 为 null）按 `sso` 处理。
+     * 新建账号的 `email_verified` 只在身份源受信任且身份邮箱已验证时为 true——不受信任的身份源可以声称任意邮箱
+     * 「已验证」，不能让它建出的账号成为日后受信任登录的合并目标。
+     * 合并写审计 `identity.linked`，新建写 `account.created`。不判断账号状态，由调用方决定（如登录拒绝停用账号）。
+     * 传 `trx` 时在调用方事务内执行；与 `link` 取同一把咨询锁，兜底用 `ON CONFLICT DO NOTHING` 后回读，
+     * 不抛唯一约束冲突、不中止调用方事务。
+     */
+    async resolve(identity, trx, opts) {
+        const id = normalize(identity);
+        const run = async (t) => {
+            await this.lockIdentity(t, id);
+            const existing = await this.findRow(t, id);
+            if (existing !== undefined) {
+                if (opts.login !== undefined)
+                    await this.allowLogin(t, id, existing, opts.login);
+                await this.refreshIdentity(t, id);
+                return { accountId: existing.accountId, created: false };
+            }
+            const merged = opts.allowMerge === true ? await this.mergeTarget(t, id) : undefined;
+            if (merged !== undefined) {
+                if (!(await this.insertIdentity(t, merged, id, "sso"))) {
+                    return { accountId: await this.mustFind(t, id), created: false };
+                }
+                await audit(t, {
+                    actorAccountId: merged,
+                    action: "identity.linked",
+                    target: merged,
+                    detail: { source: id.source, externalId: id.externalId, via: "verified_email" },
+                });
+                return { accountId: merged, created: false };
+            }
+            const accountId = randomUUID();
+            await t
+                .insertInto("accounts")
+                .values({
+                id: accountId,
+                display_name: id.displayName,
+                email: id.email ?? null,
+                email_verified: id.emailVerified && this.trusted(id.source),
+            })
+                .execute();
+            if (!(await this.insertIdentity(t, accountId, id, opts.linkedVia))) {
+                // 不走咨询锁的写入方抢先插入了同一身份：撤销刚建的账号，回读
+                await t.deleteFrom("accounts").where("id", "=", accountId).execute();
+                return { accountId: await this.mustFind(t, id), created: false };
+            }
+            await audit(t, {
+                actorAccountId: accountId,
+                action: "account.created",
+                target: accountId,
+                detail: { source: id.source, externalId: id.externalId },
+            });
+            return { accountId, created: true };
+        };
+        return trx ? run(trx) : this.db.transaction().execute(run);
+    }
+    /** 同一身份的 resolve / link 串行化（事务级咨询锁）。 */
+    async lockIdentity(t, id) {
+        await sql `SELECT pg_advisory_xact_lock(hashtext(${`capybara.identity:${id.source}:${id.externalId}`}))`.execute(t);
+    }
+    /** 身份源键（`<插件名>:<租户 id>`）是否在 `auth.trustedIdentitySources` 中：按完整键比较，信任按租户（Ruling A19）。 */
+    trusted(source) {
+        return this.config().auth.trustedIdentitySources.includes(source);
+    }
+    async findRow(t, id) {
+        const row = await t
+            .selectFrom("identities")
+            .select(["account_id", "linked_via"])
+            .where("source", "=", id.source)
+            .where("external_id", "=", id.externalId)
+            .executeTakeFirst();
+        return row && { accountId: row.account_id, linkedVia: row.linked_via };
+    }
+    /** 第三方登录能否用这一行（见 {@link resolve}）：只有 `bind` 行需要同一账号的会话，放行时把行改为 `sso`。 */
+    async allowLogin(t, id, row, login) {
+        const via = row.linkedVia ?? "sso";
+        if (via !== "bind")
+            return;
+        if (login.sessionAccountId !== row.accountId)
+            throw new IdentityNotVerified();
+        await t
+            .updateTable("identities")
+            .set({ linked_via: "sso" })
+            .where("source", "=", id.source)
+            .where("external_id", "=", id.externalId)
+            .execute();
+        await audit(t, {
+            actorAccountId: row.accountId,
+            action: "identity.verified",
+            target: row.accountId,
+            detail: { source: id.source, externalId: id.externalId, from: via },
+        });
+    }
+    async mustFind(t, id) {
+        const owner = await this.findAccount(id.source, id.externalId, t);
+        if (owner === undefined)
+            throw new Error("identity vanished after a conflicting insert");
+        return owner;
+    }
+    async refreshIdentity(t, id) {
+        await t
+            .updateTable("identities")
+            .set({ email: id.email ?? null, email_verified: id.emailVerified, profile: profileOf(id) })
+            .where("source", "=", id.source)
+            .where("external_id", "=", id.externalId)
+            .execute();
+    }
+    /**
+     * 可合并的既有账号：身份源键在 `auth.trustedIdentitySources` 中、身份邮箱已验证，
+     * 且恰好有一个邮箱已验证、邮箱相同（不区分大小写）的账号；否则 undefined（多个候选时不猜，新建）。
+     */
+    async mergeTarget(t, id) {
+        if (!id.emailVerified || id.email === undefined || !this.trusted(id.source))
+            return undefined;
+        const rows = await t
+            .selectFrom("accounts")
+            .select("id")
+            .where("email_verified", "=", true)
+            .where(sql `lower(email)`, "=", id.email.toLowerCase())
+            .limit(2)
+            .execute();
+        return rows.length === 1 ? rows[0]?.id : undefined;
+    }
+    /** 插入身份行；已存在（主键冲突）时什么都不做并返回 false。 */
+    async insertIdentity(t, accountId, id, linkedVia) {
+        const row = await t
+            .insertInto("identities")
+            .values({
+            source: id.source,
+            external_id: id.externalId,
+            account_id: accountId,
+            email: id.email ?? null,
+            email_verified: id.emailVerified,
+            profile: profileOf(id),
+            linked_via: linkedVia,
+        })
+            .onConflict((oc) => oc.columns(["source", "external_id"]).doNothing())
+            .returning("account_id")
+            .executeTakeFirst();
+        return row !== undefined;
+    }
+    /**
+     * 把外部身份绑定到账号（IM 里点绑定链接等）：已绑定本人 → 刷新资料，幂等（不改 `linked_via`）；
+     * 已绑定他人 → `409 identity.taken`。新行记 `linked_via = bind`：这样绑定的身份只能在 IM 里代表此人，
+     * 不能直接用于第三方登录（Ruling A18）。与 `resolve` 取同一把咨询锁。新绑定写审计 `identity.linked`。
+     */
+    async link(accountId, identity, trx) {
+        const id = normalize(identity);
+        const run = async (t) => {
+            await this.lockIdentity(t, id);
+            const owner = await this.findAccount(id.source, id.externalId, t);
+            if (owner !== undefined && owner !== accountId)
+                throw taken();
+            if (owner === accountId) {
+                await this.refreshIdentity(t, id);
+                return;
+            }
+            if (!(await this.insertIdentity(t, accountId, id, "bind"))) {
+                if ((await this.mustFind(t, id)) !== accountId)
+                    throw taken();
+                return;
+            }
+            await audit(t, {
+                actorAccountId: accountId,
+                action: "identity.linked",
+                target: accountId,
+                detail: { source: id.source, externalId: id.externalId, via: "bind" },
+            });
+        };
+        return trx ? run(trx) : this.db.transaction().execute(run);
+    }
+    /**
+     * 解除本人的一个外部身份（本地登录名不可解除）；不存在或不属于本人 → `identity.not_found`；
+     * 账号没有本地密码且这是最后一个外部身份 → `409 identity.last_login_method`。审计 `identity.unlinked`。
+     */
+    async unlink(accountId, source, externalId) {
+        if (source === "local")
+            throw notFound();
+        await this.db.transaction().execute(async (t) => {
+            const r = await t
+                .deleteFrom("identities")
+                .where("source", "=", source)
+                .where("external_id", "=", externalId)
+                .where("account_id", "=", accountId)
+                .executeTakeFirst();
+            if (r.numDeletedRows === 0n)
+                throw notFound();
+            // 没有本地密码时至少还要剩一个外部身份，否则此人再也登录不了（锁账号行，串行化并发解除）
+            await t.selectFrom("accounts").select("id").where("id", "=", accountId).forUpdate().execute();
+            const password = await t
+                .selectFrom("local_passwords")
+                .select("account_id")
+                .where("account_id", "=", accountId)
+                .executeTakeFirst();
+            const others = await t
+                .selectFrom("identities")
+                .select("source")
+                .where("account_id", "=", accountId)
+                .where("source", "!=", "local")
+                .limit(1)
+                .execute();
+            if (!password && others.length === 0) {
+                throw new ApiError("identity.last_login_method", "Cannot unlink the last sign-in method of an account without a password");
+            }
+            await audit(t, {
+                actorAccountId: accountId,
+                action: "identity.unlinked",
+                target: accountId,
+                detail: { source, externalId },
+            });
+        });
+    }
+    /** 账号绑定的外部身份（不含本地登录名），按绑定时间升序。 */
+    async listForAccount(accountId) {
+        const rows = await this.db
+            .selectFrom("identities")
+            .select([
+            "source",
+            "external_id",
+            "email",
+            "email_verified",
+            "profile",
+            "linked_via",
+            "created_at",
+        ])
+            .where("account_id", "=", accountId)
+            .where("source", "!=", "local")
+            .orderBy("created_at")
+            .orderBy("source")
+            .orderBy("external_id")
+            .execute();
+        return rows.map((r) => {
+            const p = (r.profile ?? {});
+            return {
+                source: r.source,
+                externalId: r.external_id,
+                email: r.email,
+                emailVerified: r.email_verified,
+                displayName: typeof p.displayName === "string" ? p.displayName : null,
+                avatarUrl: typeof p.avatarUrl === "string" ? p.avatarUrl : null,
+                linkedVia: r.linked_via,
+                createdAt: r.created_at,
+            };
+        });
+    }
+}
+const taken = () => new ApiError("identity.taken", "This external identity is already linked to another account");
+const notFound = () => new ApiError("identity.not_found", "External identity not found");

package/dist/identity/hash.d.ts

@@ -0,0 +1,2 @@
+/** 令牌的 SHA-256 十六进制摘要：会话刷新令牌、API 令牌、邀请令牌在库里只存这个。 */
+export declare const sha256Hex: (s: string) => string;

package/dist/identity/hash.js

@@ -0,0 +1,3 @@
+import { createHash } from "node:crypto";
+/** 令牌的 SHA-256 十六进制摘要：会话刷新令牌、API 令牌、邀请令牌在库里只存这个。 */
+export const sha256Hex = (s) => createHash("sha256").update(s).digest("hex");

package/dist/identity/login.d.ts

@@ -0,0 +1,6 @@
+/** 规范化登录名（NFKC、去空白、转小写）并校验格式；身份的外部 ID 就是它。 */
+export declare function normalizeLogin(raw: string): string;
+/** 密码长度上限（防止 scrypt 被超长输入拖慢）。 */
+export declare const MAX_PASSWORD_LENGTH = 256;
+/** 密码长度 12–256。 */
+export declare function validatePassword(p: string): void;

package/dist/identity/login.js

@@ -0,0 +1,20 @@
+import { ApiError } from "../errors.js";
+const LOGIN_RE = /^[a-z0-9][a-z0-9._@+-]{2,63}$/;
+/** 规范化登录名（NFKC、去空白、转小写）并校验格式；身份的外部 ID 就是它。 */
+export function normalizeLogin(raw) {
+    const login = raw.normalize("NFKC").trim().toLowerCase();
+    if (!LOGIN_RE.test(login)) {
+        throw new ApiError("validation_failed", "Login must be 3-64 characters: letters, digits, . _ @ + -", [{ path: "login", message: "invalid login format" }]);
+    }
+    return login;
+}
+/** 密码长度上限（防止 scrypt 被超长输入拖慢）。 */
+export const MAX_PASSWORD_LENGTH = 256;
+/** 密码长度 12–256。 */
+export function validatePassword(p) {
+    if (p.length < 12 || p.length > MAX_PASSWORD_LENGTH) {
+        throw new ApiError("validation_failed", "Password must be 12-256 characters", [
+            { path: "password", message: "length must be between 12 and 256" },
+        ]);
+    }
+}

package/dist/identity/me.controller.d.ts

@@ -0,0 +1,61 @@
+import type { Logger } from "@capybara-hq/plugin-sdk";
+import type { FastifyReply, FastifyRequest } from "fastify";
+import { z } from "zod";
+import type { OrgsService } from "../orgs/orgs.service.js";
+import type { OrgRole } from "../orgs/roles.js";
+import type { Account, AccountsService } from "./accounts.js";
+import { type ApiTokenRecord, type ApiTokenService } from "./api-tokens.js";
+import { type Principal } from "./principal.js";
+import type { LoginRateLimiter } from "./rate-limit.js";
+import type { SessionService } from "./sessions.js";
+declare const ChangePasswordBody: z.ZodObject<{
+    currentPassword: z.ZodString;
+    newPassword: z.ZodString;
+}, z.core.$strip>;
+declare const TokenBody: z.ZodObject<{
+    name: z.ZodString;
+    expiresAt: z.ZodOptional<z.ZodPipe<z.ZodISODateTime, z.ZodTransform<Date, string>>>;
+}, z.core.$strip>;
+declare const CurrentOrgBody: z.ZodObject<{
+    orgId: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+type MembershipView = {
+    orgId: string;
+    slug: string;
+    name: string;
+    role: OrgRole;
+};
+/** 当前用户（`/api/v1/me`）。 */
+export declare class MeController {
+    private readonly accounts;
+    private readonly sessions;
+    private readonly orgs;
+    private readonly tokens;
+    private readonly limiter;
+    private readonly log;
+    constructor(accounts: AccountsService, sessions: SessionService, orgs: OrgsService, tokens: ApiTokenService, limiter: LoginRateLimiter, log: Logger);
+    me(principal: Principal): Promise<{
+        account: Account;
+        via: "session" | "pat";
+        currentOrgId: string | null;
+        memberships: MembershipView[];
+    }>;
+    /** 切换当前组织（仅 Web 会话）；`null` 清空。非成员或已软删除的组织 → `org.not_found`。 */
+    setCurrentOrg(principal: Principal, body: z.infer<typeof CurrentOrgBody>): Promise<void>;
+    /**
+     * 改密码：核对旧密码；成功后吊销该账号除当前会话外的所有会话，并吊销其全部个人访问令牌（R24）——
+     * 三者在同一个 PG 事务里生效，之后再尽力写 Redis 吊销标记。
+     * 核对前先占用限流额度（scope `acct`：按账号 id 10 次、按客户端 IP 50 次，与登录的 IP 额度分开），
+     * 防止拿到会话的人无限次猜旧密码；超限 → 429 `auth.rate_limited`，核对成功后清零账号计数。
+     */
+    changePassword(principal: Principal, body: z.infer<typeof ChangePasswordBody>, req: FastifyRequest, reply: FastifyReply): Promise<void>;
+    createToken(principal: Principal, body: z.infer<typeof TokenBody>): Promise<{
+        token: string;
+        record: ApiTokenRecord;
+    }>;
+    listTokens(principal: Principal): Promise<{
+        tokens: ApiTokenRecord[];
+    }>;
+    revokeToken(principal: Principal, tokenId: string): Promise<void>;
+}
+export {};