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

package/dist/identity/me.controller.js

@@ -0,0 +1,159 @@
+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, Put, Req, Res, } from "@nestjs/common";
+import { z } from "zod";
+import { ApiError } from "../errors.js";
+import { ACCOUNTS, API_TOKENS, KERNEL_LOG, ORGS, RATE_LIMITER, SESSIONS } from "../http/tokens.js";
+import { ZodPipe } from "../http/zod.pipe.js";
+import { FutureIsoDate } from "./api-tokens.js";
+import { clientMeta } from "./auth.controller.js";
+import { MAX_PASSWORD_LENGTH } from "./login.js";
+import { CurrentPrincipal, requireUser, SessionOnly } from "./principal.js";
+/** 改密码时同一账号在窗口内允许核对旧密码的次数。 */
+const CHANGE_PASSWORD_LIMIT_PER_ACCOUNT = 10;
+const ChangePasswordBody = z.object({
+    currentPassword: z.string().min(1),
+    newPassword: z.string().min(12).max(MAX_PASSWORD_LENGTH),
+});
+const TokenBody = z.object({
+    name: z.string().min(1).max(100),
+    expiresAt: FutureIsoDate.optional(),
+});
+const CurrentOrgBody = z.object({ orgId: z.string().min(1).nullable() });
+/** 当前用户（`/api/v1/me`）。 */
+let MeController = class MeController {
+    accounts;
+    sessions;
+    orgs;
+    tokens;
+    limiter;
+    log;
+    constructor(accounts, sessions, orgs, tokens, limiter, log) {
+        this.accounts = accounts;
+        this.sessions = sessions;
+        this.orgs = orgs;
+        this.tokens = tokens;
+        this.limiter = limiter;
+        this.log = log;
+    }
+    async me(principal) {
+        const p = requireUser(principal);
+        const currentOrgId = p.via === "session" ? ((await this.sessions.get(p.sessionId))?.currentOrgId ?? null) : null;
+        const memberships = (await this.orgs.listForAccount(p.account.id)).map((o) => ({
+            orgId: o.id,
+            slug: o.slug,
+            name: o.name,
+            role: o.role,
+        }));
+        return { account: p.account, via: p.via, currentOrgId, memberships };
+    }
+    /** 切换当前组织（仅 Web 会话）；`null` 清空。非成员或已软删除的组织 → `org.not_found`。 */
+    async setCurrentOrg(principal, body) {
+        const p = requireUser(principal);
+        if (p.via !== "session") {
+            throw new ApiError("auth.session_required", "This endpoint requires a web session");
+        }
+        await this.sessions.switchCurrentOrg(p.sessionId, p.account.id, body.orgId);
+    }
+    /**
+     * 改密码：核对旧密码；成功后吊销该账号除当前会话外的所有会话，并吊销其全部个人访问令牌（R24）——
+     * 三者在同一个 PG 事务里生效，之后再尽力写 Redis 吊销标记。
+     * 核对前先占用限流额度（scope `acct`：按账号 id 10 次、按客户端 IP 50 次，与登录的 IP 额度分开），
+     * 防止拿到会话的人无限次猜旧密码；超限 → 429 `auth.rate_limited`，核对成功后清零账号计数。
+     */
+    async changePassword(principal, body, req, reply) {
+        const p = requireUser(principal);
+        if (p.via !== "session") {
+            throw new ApiError("auth.session_required", "This endpoint requires a web session");
+        }
+        const { ip } = clientMeta(req);
+        const rl = await this.limiter.reserveScoped("acct", p.account.id, ip, CHANGE_PASSWORD_LIMIT_PER_ACCOUNT);
+        if (!rl.allowed) {
+            reply.header("retry-after", String(rl.retryAfterSeconds));
+            throw new ApiError("auth.rate_limited", "Too many failed password attempts; try again later");
+        }
+        if (!(await this.accounts.verifyPassword(p.account.id, body.currentPassword))) {
+            throw new ApiError("auth.invalid_credentials", "Current password is incorrect");
+        }
+        await this.limiter.succeededScoped("acct", p.account.id, ip);
+        // 新密码、吊销其他会话（PG revoked_at）与个人令牌在同一个 PG 事务里完成
+        const revoked = await this.accounts.changePassword(p.account.id, body.newPassword, p.sessionId);
+        try {
+            await this.sessions.markRevoked(revoked);
+        }
+        catch (err) {
+            // Redis 标记只是快速路径：鉴权每次都查 PG revoked_at，这些会话已经无法使用
+            this.log.warn("failed to write session revocation markers after password change", {
+                accountId: p.account.id,
+                err,
+            });
+        }
+    }
+    async createToken(principal, body) {
+        const p = requireUser(principal);
+        return this.tokens.createPersonal(p.account.id, body);
+    }
+    async listTokens(principal) {
+        const p = requireUser(principal);
+        return { tokens: await this.tokens.list({ accountId: p.account.id }) };
+    }
+    async revokeToken(principal, tokenId) {
+        const p = requireUser(principal);
+        await this.tokens.revoke(tokenId, { accountId: p.account.id });
+    }
+};
+__decorate([
+    Get(),
+    __param(0, CurrentPrincipal())
+], MeController.prototype, "me", null);
+__decorate([
+    Put("current-org"),
+    SessionOnly(),
+    HttpCode(204),
+    __param(0, CurrentPrincipal()),
+    __param(1, Body(new ZodPipe(CurrentOrgBody)))
+], MeController.prototype, "setCurrentOrg", null);
+__decorate([
+    Put("password"),
+    SessionOnly(),
+    HttpCode(204),
+    __param(0, CurrentPrincipal()),
+    __param(1, Body(new ZodPipe(ChangePasswordBody))),
+    __param(2, Req()),
+    __param(3, Res({ passthrough: true }))
+], MeController.prototype, "changePassword", null);
+__decorate([
+    Post("tokens"),
+    SessionOnly(),
+    __param(0, CurrentPrincipal()),
+    __param(1, Body(new ZodPipe(TokenBody)))
+], MeController.prototype, "createToken", null);
+__decorate([
+    Get("tokens"),
+    SessionOnly(),
+    __param(0, CurrentPrincipal())
+], MeController.prototype, "listTokens", null);
+__decorate([
+    Delete("tokens/:tokenId"),
+    SessionOnly(),
+    HttpCode(204),
+    __param(0, CurrentPrincipal()),
+    __param(1, Param("tokenId"))
+], MeController.prototype, "revokeToken", null);
+MeController = __decorate([
+    Controller("api/v1/me"),
+    __param(0, Inject(ACCOUNTS)),
+    __param(1, Inject(SESSIONS)),
+    __param(2, Inject(ORGS)),
+    __param(3, Inject(API_TOKENS)),
+    __param(4, Inject(RATE_LIMITER)),
+    __param(5, Inject(KERNEL_LOG))
+], MeController);
+export { MeController };

package/dist/identity/passwords.d.ts

@@ -0,0 +1,6 @@
+/** 哈希密码，格式 `scrypt$1$N$r$p$<salt b64>$<hash b64>`。 */
+export declare function hashPassword(plain: string): Promise<string>;
+/** 校验密码；格式不认识（含参数不符）一律返回 false，不抛错。 */
+export declare function verifyPassword(stored: string, plain: string): Promise<boolean>;
+/** 账号不存在时也跑一次校验，防止按耗时枚举登录名。 */
+export declare const DUMMY_PASSWORD_HASH: string;

package/dist/identity/passwords.js

@@ -0,0 +1,37 @@
+import { randomBytes, scrypt, timingSafeEqual } from "node:crypto";
+const N = 32768;
+const R = 8;
+const P = 1;
+const KEYLEN = 32;
+const MAXMEM = 64 * 1024 * 1024;
+function derive(plain, salt) {
+    return new Promise((resolve, reject) => {
+        scrypt(plain, salt, KEYLEN, { N, r: R, p: P, maxmem: MAXMEM }, (err, key) => err ? reject(err) : resolve(key));
+    });
+}
+/** 哈希密码，格式 `scrypt$1$N$r$p$<salt b64>$<hash b64>`。 */
+export async function hashPassword(plain) {
+    const salt = randomBytes(16);
+    const hash = await derive(plain, salt);
+    return `scrypt$1$${N}$${R}$${P}$${salt.toString("base64")}$${hash.toString("base64")}`;
+}
+/** 校验密码；格式不认识（含参数不符）一律返回 false，不抛错。 */
+export async function verifyPassword(stored, plain) {
+    const parts = stored.split("$");
+    if (parts.length !== 7 || parts[0] !== "scrypt" || parts[1] !== "1")
+        return false;
+    if (parts[2] !== String(N) || parts[3] !== String(R) || parts[4] !== String(P))
+        return false;
+    const salt = Buffer.from(parts[5] ?? "", "base64");
+    const expected = Buffer.from(parts[6] ?? "", "base64");
+    if (salt.length === 0 || expected.length !== KEYLEN)
+        return false;
+    try {
+        return timingSafeEqual(await derive(plain, salt), expected);
+    }
+    catch {
+        return false;
+    }
+}
+/** 账号不存在时也跑一次校验，防止按耗时枚举登录名。 */
+export const DUMMY_PASSWORD_HASH = `scrypt$1$${N}$${R}$${P}$${Buffer.alloc(16, 1).toString("base64")}$${Buffer.alloc(KEYLEN, 2).toString("base64")}`;

package/dist/identity/principal.d.ts

@@ -0,0 +1,56 @@
+import type { Account } from "./accounts.js";
+/** 一个请求的调用者：Web 会话或个人令牌代表的账号，或属于某组织的服务令牌。 */
+export type Principal = {
+    kind: "user";
+    account: Account;
+    via: "session";
+    sessionId: string;
+} | {
+    kind: "user";
+    account: Account;
+    via: "pat";
+    tokenId: string;
+} | {
+    kind: "service";
+    tokenId: string;
+    orgId: string;
+    role: "admin" | "member" | "guest";
+};
+/** user principal。 */
+export type UserPrincipal = Extract<Principal, {
+    kind: "user";
+}>;
+declare module "fastify" {
+    interface FastifyRequest {
+        /** 由 AuthGuard 设置；`@Public` 路由上无凭据时为 undefined。 */
+        principal?: Principal;
+    }
+}
+export declare const PUBLIC_KEY = "capybara:auth:public";
+export declare const SESSION_ONLY_KEY = "capybara:auth:session-only";
+export declare const ENTERPRISE_ADMIN_KEY = "capybara:auth:enterprise-admin";
+export declare const ALLOW_SERVICE_KEY = "capybara:auth:allow-service";
+/**
+ * 不要求凭据：无凭据时放行（principal 为 undefined）；带了有效凭据仍解析，无效凭据按无凭据处理。
+ * 非安全方法照样要求 `X-Capybara-Csrf: 1`（防登录 CSRF）。新增公开路由必须同时更新 public-routes 元测试的清单。
+ */
+export declare const Public: () => MethodDecorator & ClassDecorator;
+/** 仅接受 Web 会话（`via: "session"`）；个人令牌 → `auth.session_required`。 */
+export declare const SessionOnly: () => MethodDecorator;
+/** 仅企业管理员（user principal 且 `isEnterpriseAdmin`）；否则 `forbidden`。 */
+export declare const EnterpriseAdmin: () => MethodDecorator & ClassDecorator;
+/**
+ * 允许服务令牌（service principal）访问。默认拒绝：未标注的路由只接受 user principal，service → `forbidden`。
+ * 组织级路由由 OrgGuard 再核对令牌所属组织与角色。
+ */
+export declare const AllowService: () => MethodDecorator & ClassDecorator;
+/** 参数装饰器：取 AuthGuard 放在 `req.principal` 上的调用者。 */
+export declare const CurrentPrincipal: () => ParameterDecorator;
+/**
+ * 收窄为 user principal；service → `forbidden`。
+ * principal 缺失说明路由被误标 `@Public()`（非公开路由上 AuthGuard 必然已设置 principal）：
+ * 抛普通 Error（500）让错误显形，而不是在 handler 里补一个 `auth.required` 掩盖它（public-routes 元测试靠此发现误标）。
+ */
+export declare function requireUser(p: Principal | undefined): UserPrincipal;
+/** 个人令牌发起的请求返回令牌 id（供审计 `actor_token_id`），Web 会话返回 undefined。 */
+export declare function patTokenId(p: UserPrincipal): string | undefined;

package/dist/identity/principal.js

@@ -0,0 +1,38 @@
+import { createParamDecorator, SetMetadata } from "@nestjs/common";
+import { ApiError } from "../errors.js";
+export const PUBLIC_KEY = "capybara:auth:public";
+export const SESSION_ONLY_KEY = "capybara:auth:session-only";
+export const ENTERPRISE_ADMIN_KEY = "capybara:auth:enterprise-admin";
+export const ALLOW_SERVICE_KEY = "capybara:auth:allow-service";
+/**
+ * 不要求凭据：无凭据时放行（principal 为 undefined）；带了有效凭据仍解析，无效凭据按无凭据处理。
+ * 非安全方法照样要求 `X-Capybara-Csrf: 1`（防登录 CSRF）。新增公开路由必须同时更新 public-routes 元测试的清单。
+ */
+export const Public = () => SetMetadata(PUBLIC_KEY, true);
+/** 仅接受 Web 会话（`via: "session"`）；个人令牌 → `auth.session_required`。 */
+export const SessionOnly = () => SetMetadata(SESSION_ONLY_KEY, true);
+/** 仅企业管理员（user principal 且 `isEnterpriseAdmin`）；否则 `forbidden`。 */
+export const EnterpriseAdmin = () => SetMetadata(ENTERPRISE_ADMIN_KEY, true);
+/**
+ * 允许服务令牌（service principal）访问。默认拒绝：未标注的路由只接受 user principal，service → `forbidden`。
+ * 组织级路由由 OrgGuard 再核对令牌所属组织与角色。
+ */
+export const AllowService = () => SetMetadata(ALLOW_SERVICE_KEY, true);
+/** 参数装饰器：取 AuthGuard 放在 `req.principal` 上的调用者。 */
+export const CurrentPrincipal = createParamDecorator((_data, ctx) => ctx.switchToHttp().getRequest().principal);
+/**
+ * 收窄为 user principal；service → `forbidden`。
+ * principal 缺失说明路由被误标 `@Public()`（非公开路由上 AuthGuard 必然已设置 principal）：
+ * 抛普通 Error（500）让错误显形，而不是在 handler 里补一个 `auth.required` 掩盖它（public-routes 元测试靠此发现误标）。
+ */
+export function requireUser(p) {
+    if (!p)
+        throw new Error("requireUser: no principal; is this route wrongly marked @Public()?");
+    if (p.kind !== "user")
+        throw new ApiError("forbidden", "This endpoint requires a user");
+    return p;
+}
+/** 个人令牌发起的请求返回令牌 id（供审计 `actor_token_id`），Web 会话返回 undefined。 */
+export function patTokenId(p) {
+    return p.via === "pat" ? p.tokenId : undefined;
+}

package/dist/identity/rate-limit.d.ts

@@ -0,0 +1,55 @@
+import type { Redis } from "ioredis";
+/** 计数窗口（秒）：首次尝试起算，窗口内累计。 */
+export declare const LOGIN_FAIL_WINDOW_SECONDS = 900;
+/** 同一（登录名, 客户端 IP）在窗口内允许的尝试次数（成功登录会清零）。 */
+export declare const LOGIN_FAIL_LIMIT_PER_LOGIN_IP = 10;
+/** 同一客户端 IP 在窗口内允许的尝试次数（跨登录名，防撞库；成功登录退还一次）。 */
+export declare const LOGIN_FAIL_LIMIT_PER_IP = 50;
+/** 同一登录名在窗口内跨所有 IP 允许的尝试次数（防分布式爆破单个账号；成功登录会清零）。 */
+export declare const LOGIN_FAIL_LIMIT_PER_LOGIN = 100;
+export type RateLimitResult = {
+    allowed: true;
+} | {
+    allowed: false;
+    retryAfterSeconds: number;
+};
+/** 登录计数键。 */
+export declare const loginFailKey: {
+    /** （登录名, IP）：阈值 10。 */
+    loginIp: (login: string, ip: string) => string;
+    /** 客户端 IP（跨登录名）：阈值 50。 */
+    ip: (ip: string) => string;
+    /** 单登录名全局（跨 IP）：阈值 100。 */
+    login: (login: string) => string;
+};
+/** 其他凭据核对接口（改密码 `acct`、初始化令牌 `setup`、接受邀请 `inv`）的计数键，与登录的额度分开。 */
+export declare const scopedKey: {
+    key: (scope: string, key: string) => string;
+    ip: (scope: string, ip: string) => string;
+};
+/**
+ * 凭据尝试限流，计数在 Redis 中、所有副本共享，窗口 900s。
+ *
+ * 登录（`reserve`）按三个键计数，任一超限即拒绝：
+ * - （登录名, IP）10 次——攻击者从一个 IP 打满某登录名的额度，不影响本人从别的 IP 登录（R25）；
+ * - 客户端 IP 50 次（跨登录名，防撞库）；
+ * - 单登录名 100 次（跨 IP，防分布式爆破）。
+ * 校验密码**之前**先原子地占用一次尝试，并发请求也无法绕过上限；登录成功后 `succeeded`
+ * 清掉该登录名的两个计数并退还一次 IP 额度（成功登录不消耗 IP 预算）。
+ *
+ * `reserveScoped` 供其他核对凭据的接口复用：按 `(scope, key)`（上限 `limit`）与 scope 内的 IP
+ * （上限 `ipLimit`，默认同登录的 50）两个键计数；IP 计数与登录的 IP 额度分开
+ * （改密码失败不会挤占同 NAT 下他人的登录额度）。
+ *
+ * 被拒绝的尝试不递增任何计数（攻击者在一个维度上被拒后，无法继续推高其他维度的计数），窗口到期自然清零。
+ */
+export declare class LoginRateLimiter {
+    private readonly redis;
+    constructor(redis: Redis);
+    reserve(login: string, ip: string): Promise<RateLimitResult>;
+    succeeded(login: string, ip: string): Promise<void>;
+    reserveScoped(scope: string, key: string, ip: string, limit: number, ipLimit?: number): Promise<RateLimitResult>;
+    /** 核对成功：删 `(scope, key)` 计数，scope 内 IP 计数减一。 */
+    succeededScoped(scope: string, key: string, ip: string): Promise<void>;
+    private reserveKeys;
+}

package/dist/identity/rate-limit.js

@@ -0,0 +1,121 @@
+import { createHash } from "node:crypto";
+/** 计数窗口（秒）：首次尝试起算，窗口内累计。 */
+export const LOGIN_FAIL_WINDOW_SECONDS = 900;
+/** 同一（登录名, 客户端 IP）在窗口内允许的尝试次数（成功登录会清零）。 */
+export const LOGIN_FAIL_LIMIT_PER_LOGIN_IP = 10;
+/** 同一客户端 IP 在窗口内允许的尝试次数（跨登录名，防撞库；成功登录退还一次）。 */
+export const LOGIN_FAIL_LIMIT_PER_IP = 50;
+/** 同一登录名在窗口内跨所有 IP 允许的尝试次数（防分布式爆破单个账号；成功登录会清零）。 */
+export const LOGIN_FAIL_LIMIT_PER_LOGIN = 100;
+/**
+ * 原子地「先查后增」：ARGV[1] 为窗口秒数，ARGV[i + 1] 为 KEYS[i] 的上限。
+ * 先读全部计数，任一已达上限即拒绝，且**不递增任何键**（被拒绝的尝试不消耗其他计数，
+ * 否则从一个 IP 被拒的请求会继续推高单登录名全局计数，把本人从别的 IP 也锁住）；
+ * 都未达上限才逐个 INCR，并在首次计数或键没有 TTL 时设 EXPIRE（保证计数键一定带 TTL）。
+ * 返回 `{1}`（放行）或 `{0, retryTtl}`（拒绝；retryTtl 为已达上限的键中最大的剩余 TTL）。
+ */
+const RESERVE = `
+local retry = -1
+for i, key in ipairs(KEYS) do
+  local n = tonumber(redis.call('GET', key) or '0')
+  if n >= tonumber(ARGV[i + 1]) then
+    local ttl = redis.call('TTL', key)
+    if ttl > retry then retry = ttl end
+    if retry < 1 then retry = 1 end
+  end
+end
+if retry > 0 then
+  return {0, retry}
+end
+for i, key in ipairs(KEYS) do
+  local n = redis.call('INCR', key)
+  if n == 1 or redis.call('TTL', key) < 0 then
+    redis.call('EXPIRE', key, ARGV[1])
+  end
+end
+return {1}
+`;
+/**
+ * 删除除最后一个之外的全部键；最后一个（IP 计数）存在时减一，减到 0 及以下即删除
+ * （不会凭空建出无 TTL 的负数键）。
+ */
+const SUCCEEDED = `
+for i = 1, #KEYS - 1 do
+  redis.call('DEL', KEYS[i])
+end
+local ip = KEYS[#KEYS]
+if redis.call('EXISTS', ip) == 1 then
+  if redis.call('DECR', ip) <= 0 then
+    redis.call('DEL', ip)
+  end
+end
+return 0
+`;
+const sha256 = (s) => createHash("sha256").update(s).digest("hex");
+/** 登录名按与本地账号相同的方式粗规范化（不校验格式），使大小写 / 空白变体共用计数。 */
+const loginHash = (login) => sha256(login.normalize("NFKC").trim().toLowerCase());
+/** 登录计数键。 */
+export const loginFailKey = {
+    /** （登录名, IP）：阈值 10。 */
+    loginIp: (login, ip) => `capk:login-fail:li:${loginHash(login)}:${sha256(ip)}`,
+    /** 客户端 IP（跨登录名）：阈值 50。 */
+    ip: (ip) => `capk:login-fail:ip:${ip}`,
+    /** 单登录名全局（跨 IP）：阈值 100。 */
+    login: (login) => `capk:login-fail:l:${loginHash(login)}`,
+};
+/** 其他凭据核对接口（改密码 `acct`、初始化令牌 `setup`、接受邀请 `inv`）的计数键，与登录的额度分开。 */
+export const scopedKey = {
+    key: (scope, key) => `capk:rl:${scope}:k:${sha256(key)}`,
+    ip: (scope, ip) => `capk:rl:${scope}:ip:${ip}`,
+};
+/**
+ * 凭据尝试限流，计数在 Redis 中、所有副本共享，窗口 900s。
+ *
+ * 登录（`reserve`）按三个键计数，任一超限即拒绝：
+ * - （登录名, IP）10 次——攻击者从一个 IP 打满某登录名的额度，不影响本人从别的 IP 登录（R25）；
+ * - 客户端 IP 50 次（跨登录名，防撞库）；
+ * - 单登录名 100 次（跨 IP，防分布式爆破）。
+ * 校验密码**之前**先原子地占用一次尝试，并发请求也无法绕过上限；登录成功后 `succeeded`
+ * 清掉该登录名的两个计数并退还一次 IP 额度（成功登录不消耗 IP 预算）。
+ *
+ * `reserveScoped` 供其他核对凭据的接口复用：按 `(scope, key)`（上限 `limit`）与 scope 内的 IP
+ * （上限 `ipLimit`，默认同登录的 50）两个键计数；IP 计数与登录的 IP 额度分开
+ * （改密码失败不会挤占同 NAT 下他人的登录额度）。
+ *
+ * 被拒绝的尝试不递增任何计数（攻击者在一个维度上被拒后，无法继续推高其他维度的计数），窗口到期自然清零。
+ */
+export class LoginRateLimiter {
+    redis;
+    constructor(redis) {
+        this.redis = redis;
+    }
+    async reserve(login, ip) {
+        return this.reserveKeys([
+            [loginFailKey.loginIp(login, ip), LOGIN_FAIL_LIMIT_PER_LOGIN_IP],
+            [loginFailKey.ip(ip), LOGIN_FAIL_LIMIT_PER_IP],
+            [loginFailKey.login(login), LOGIN_FAIL_LIMIT_PER_LOGIN],
+        ]);
+    }
+    async succeeded(login, ip) {
+        await this.redis.eval(SUCCEEDED, 3, loginFailKey.loginIp(login, ip), loginFailKey.login(login), loginFailKey.ip(ip));
+    }
+    async reserveScoped(scope, key, ip, limit, ipLimit = LOGIN_FAIL_LIMIT_PER_IP) {
+        return this.reserveKeys([
+            [scopedKey.key(scope, key), limit],
+            [scopedKey.ip(scope, ip), ipLimit],
+        ]);
+    }
+    /** 核对成功：删 `(scope, key)` 计数，scope 内 IP 计数减一。 */
+    async succeededScoped(scope, key, ip) {
+        await this.redis.eval(SUCCEEDED, 2, scopedKey.key(scope, key), scopedKey.ip(scope, ip));
+    }
+    async reserveKeys(keys) {
+        const out = (await this.redis.eval(RESERVE, keys.length, ...keys.map(([k]) => k), LOGIN_FAIL_WINDOW_SECONDS, ...keys.map(([, limit]) => limit)));
+        if (out[0] === 1)
+            return { allowed: true };
+        return { allowed: false, retryAfterSeconds: clampTtl(out[1] ?? LOGIN_FAIL_WINDOW_SECONDS) };
+    }
+}
+function clampTtl(ttl) {
+    return Math.min(Math.max(ttl, 1), LOGIN_FAIL_WINDOW_SECONDS);
+}

package/dist/identity/sessions.d.ts

@@ -0,0 +1,84 @@
+import type { Redis } from "ioredis";
+import type { Keyring } from "../ctx/secrets.js";
+import type { KernelDb } from "../db/kernel-schema.js";
+import { type Account } from "./accounts.js";
+export interface IssuedSession {
+    sessionId: string;
+    accountId: string;
+    accessToken: string;
+    refreshToken: string;
+    accessExpiresAt: Date;
+    refreshExpiresAt: Date;
+}
+/** 旧 refresh token 在被轮换后多久内重放视为并发刷新（不吊销会话）。 */
+export declare const REFRESH_RACE_GRACE_MS = 30000;
+/**
+ * Web 会话服务：短期 access token（HS256 JWT，密钥由主密钥环派生）+ PG 中可吊销、一次一换的 refresh token。
+ * 吊销会在 Redis 写 `capk:revoked-sid:<sid>`（TTL 覆盖任何配置下 access token 的最长剩余寿命），使所有副本立即拒绝该会话的 access token；
+ * 验证 access token 时还会读 PG 的 `sessions.revoked_at`，Redis 丢数据也不会让已吊销的会话复活。
+ * 框架无关，由调用方注入依赖。
+ */
+export declare class SessionService {
+    private readonly db;
+    private readonly redis;
+    private readonly opts;
+    private readonly keys;
+    constructor(db: KernelDb, redis: Redis, keyring: Keyring, opts: {
+        accessTtlSeconds: number;
+        refreshTtlDays: number;
+    });
+    /**
+     * 新建会话。传入 `trx` 时会话行在调用方的事务里写入（如初始化、凭邀请注册：与账号同一事务，
+     * 失败整体回滚）；Cookie 由调用方在提交之后再设置。
+     */
+    create(accountId: string, meta: {
+        userAgent?: string;
+        ip?: string;
+    }, trx?: KernelDb): Promise<IssuedSession>;
+    refresh(refreshToken: string, meta: {
+        userAgent?: string;
+        ip?: string;
+    }): Promise<IssuedSession>;
+    /** 旧 refresh token 未能轮换：区分并发刷新（宽限期内）与重放（吊销会话）。 */
+    private rejectRefresh;
+    /**
+     * 验证 access token 并读出会话所属账号（不判断账号状态，由调用方决定）。
+     * Redis 吊销标记是快速路径；PG 的 `sessions.revoked_at` 才是事实来源——Redis 被清空 / 故障切换丢数据时，
+     * 已登出或因改密码被吊销的会话不能复活（spec 8.1）。吊销检查与账号读取合并为一条按主键的 JOIN 查询。
+     */
+    verifyAccess(accessToken: string): Promise<{
+        accountId: string;
+        sessionId: string;
+        account: Account;
+    }>;
+    /**
+     * 只验签不看过期，供登出使用：过期的 token 也接受（取 `JWTExpired` 里已验签的 payload）；
+     * 签名无效或缺 sid 返回 undefined。
+     */
+    sessionIdFromAccess(accessToken: string): Promise<string | undefined>;
+    /** 按 refresh token 吊销其当前会话（供登出使用）；无匹配则什么都不做。 */
+    revokeByRefresh(refreshToken: string): Promise<void>;
+    revoke(sessionId: string): Promise<void>;
+    revokeAllForAccount(accountId: string, exceptSessionId?: string): Promise<number>;
+    /**
+     * 给已在 PG 中吊销的会话写 Redis 吊销标记（快速路径）；任一写入失败即抛出。
+     * 鉴权以 PG `revoked_at` 为准，调用方可以把这一步当作尽力而为。
+     */
+    markRevoked(sessionIds: string[]): Promise<void>;
+    /** 设当前组织；会话已吊销、已过期或不存在 → `auth.session_revoked`。 */
+    setCurrentOrg(sessionId: string, orgId: string | null): Promise<void>;
+    /**
+     * 切换当前组织（Web 会话）：同一事务内先 `SELECT … FROM memberships WHERE org_id = $1 AND account_id = $2 FOR SHARE`
+     * 锁住这一条成员关系（且组织未软删除），再写会话——与「移出成员」（DELETE memberships 后清空会话当前组织）互斥，
+     * 不会留下指向已移出组织的 `current_org_id`。非成员或组织已软删除 → `org.not_found`；`null` 清空，不查成员关系。
+     */
+    switchCurrentOrg(sessionId: string, accountId: string, orgId: string | null): Promise<void>;
+    /** 有效（未吊销且未过期）的会话；否则返回 undefined。 */
+    get(sessionId: string): Promise<{
+        id: string;
+        accountId: string;
+        currentOrgId: string | null;
+    } | undefined>;
+    private readonly keyFor;
+    private issue;
+}