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

package/dist/identity/sessions.js

@@ -0,0 +1,306 @@
+import { randomBytes, randomUUID } from "node:crypto";
+import { errors as joseErrors, jwtVerify, SignJWT } from "jose";
+import { sql } from "kysely";
+import { ACCESS_TOKEN_TTL_MAX_SECONDS } from "../config/schema.js";
+import { ApiError } from "../errors.js";
+import { ACCOUNT_COLUMNS, toAccount } from "./accounts.js";
+import { sha256Hex } from "./hash.js";
+/** 旧 refresh token 在被轮换后多久内重放视为并发刷新（不吊销会话）。 */
+export const REFRESH_RACE_GRACE_MS = 30_000;
+const REFRESH_PREFIX = "cap_rt_";
+const ACCESS_KEY_INFO = "access-token/v1";
+const revokedKey = (sid) => `capk:revoked-sid:${sid}`;
+/**
+ * 吊销标记的 TTL：按 schema 允许的 access token 最长寿命 + 60s 计算，而不是本实例配置的寿命——
+ * 滚动修改 `auth.accessTokenTtlSeconds` 时，按旧（更长）寿命签发的 token 不会在标记过期后复活。
+ */
+const REVOKED_MARKER_TTL_SECONDS = ACCESS_TOKEN_TTL_MAX_SECONDS + 60;
+const VERIFY_OPTS = { algorithms: ["HS256"], requiredClaims: ["exp", "sub"] };
+const newRefreshToken = () => REFRESH_PREFIX + randomBytes(32).toString("base64url");
+/** 按 JWS 头里的 kid 选派生密钥；找不到时抛出，由调用方映射为 `auth.required`。 */
+class UnknownKidError extends Error {
+}
+/**
+ * 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 class SessionService {
+    db;
+    redis;
+    opts;
+    keys;
+    constructor(db, redis, keyring, opts) {
+        this.db = db;
+        this.redis = redis;
+        this.opts = opts;
+        this.keys = keyring.deriveKey(ACCESS_KEY_INFO);
+    }
+    /**
+     * 新建会话。传入 `trx` 时会话行在调用方的事务里写入（如初始化、凭邀请注册：与账号同一事务，
+     * 失败整体回滚）；Cookie 由调用方在提交之后再设置。
+     */
+    async create(accountId, meta, trx) {
+        const id = randomUUID();
+        const refreshToken = newRefreshToken();
+        const row = await (trx ?? this.db)
+            .insertInto("sessions")
+            .values({
+            id,
+            account_id: accountId,
+            refresh_hash: sha256Hex(refreshToken),
+            user_agent: meta.userAgent ?? null,
+            ip: meta.ip ?? null,
+            expires_at: sql `now() + make_interval(days => ${this.opts.refreshTtlDays})`,
+        })
+            .returning(["expires_at"])
+            .executeTakeFirstOrThrow();
+        return this.issue(id, accountId, refreshToken, row.expires_at);
+    }
+    async refresh(refreshToken, meta) {
+        const oldHash = sha256Hex(refreshToken);
+        const next = newRefreshToken();
+        // 原子轮换：并发的两次刷新只有一个能匹配 refresh_hash = old
+        const row = await this.db
+            .updateTable("sessions")
+            .set((eb) => ({
+            prev_refresh_hash: eb.ref("refresh_hash"),
+            refresh_hash: sha256Hex(next),
+            rotated_at: sql `now()`,
+            last_used_at: sql `now()`,
+            ...(meta.userAgent !== undefined && { user_agent: meta.userAgent }),
+            ...(meta.ip !== undefined && { ip: meta.ip }),
+        }))
+            .where("refresh_hash", "=", oldHash)
+            .where("revoked_at", "is", null)
+            .where("expires_at", ">", sql `now()`)
+            .returning(["id", "account_id", "expires_at"])
+            .executeTakeFirst();
+        if (!row)
+            return this.rejectRefresh(oldHash);
+        const account = await this.db
+            .selectFrom("accounts")
+            .select("status")
+            .where("id", "=", row.account_id)
+            .executeTakeFirst();
+        if (account?.status !== "active") {
+            await this.revoke(row.id);
+            throw new ApiError("auth.account_disabled", "Account is disabled");
+        }
+        return this.issue(row.id, row.account_id, next, row.expires_at);
+    }
+    /** 旧 refresh token 未能轮换：区分并发刷新（宽限期内）与重放（吊销会话）。 */
+    async rejectRefresh(oldHash) {
+        const prev = await this.db
+            .selectFrom("sessions")
+            .select((eb) => [
+            "id",
+            eb
+                .and([
+                eb("revoked_at", "is", null),
+                eb("expires_at", ">", sql `now()`),
+                eb("rotated_at", ">", sql `now() - make_interval(secs => ${REFRESH_RACE_GRACE_MS / 1000})`),
+            ])
+                .as("in_grace"),
+        ])
+            .where("prev_refresh_hash", "=", oldHash)
+            .executeTakeFirst();
+        if (prev?.in_grace) {
+            throw new ApiError("auth.refresh_race", "Refresh token was just rotated by another request");
+        }
+        if (prev)
+            await this.revoke(prev.id);
+        throw new ApiError("auth.refresh_invalid", "Refresh token is invalid");
+    }
+    /**
+     * 验证 access token 并读出会话所属账号（不判断账号状态，由调用方决定）。
+     * Redis 吊销标记是快速路径；PG 的 `sessions.revoked_at` 才是事实来源——Redis 被清空 / 故障切换丢数据时，
+     * 已登出或因改密码被吊销的会话不能复活（spec 8.1）。吊销检查与账号读取合并为一条按主键的 JOIN 查询。
+     */
+    async verifyAccess(accessToken) {
+        let sub;
+        let sid;
+        try {
+            const { payload } = await jwtVerify(accessToken, this.keyFor, VERIFY_OPTS);
+            sub = payload.sub;
+            sid = payload.sid;
+        }
+        catch (e) {
+            if (e instanceof joseErrors.JWTExpired) {
+                throw new ApiError("auth.token_expired", "Access token has expired");
+            }
+            throw new ApiError("auth.required", "Authentication required");
+        }
+        if (typeof sub !== "string" || typeof sid !== "string") {
+            throw new ApiError("auth.required", "Authentication required");
+        }
+        if (await this.redis.exists(revokedKey(sid))) {
+            throw new ApiError("auth.session_revoked", "Session has been revoked");
+        }
+        const row = await this.db
+            .selectFrom("sessions")
+            .innerJoin("accounts", "accounts.id", "sessions.account_id")
+            .select(["sessions.revoked_at", ...ACCOUNT_COLUMNS])
+            .where("sessions.id", "=", sid)
+            .executeTakeFirst();
+        if (!row || row.revoked_at !== null) {
+            throw new ApiError("auth.session_revoked", "Session has been revoked");
+        }
+        if (row.id !== sub)
+            throw new ApiError("auth.required", "Authentication required");
+        return { accountId: sub, sessionId: sid, account: toAccount(row) };
+    }
+    /**
+     * 只验签不看过期，供登出使用：过期的 token 也接受（取 `JWTExpired` 里已验签的 payload）；
+     * 签名无效或缺 sid 返回 undefined。
+     */
+    async sessionIdFromAccess(accessToken) {
+        let sid;
+        try {
+            sid = (await jwtVerify(accessToken, this.keyFor, VERIFY_OPTS)).payload.sid;
+        }
+        catch (e) {
+            // JWTExpired 只会在签名校验通过之后抛出，其 payload 可信
+            if (!(e instanceof joseErrors.JWTExpired))
+                return undefined;
+            sid = e.payload.sid;
+        }
+        return typeof sid === "string" ? sid : undefined;
+    }
+    /** 按 refresh token 吊销其当前会话（供登出使用）；无匹配则什么都不做。 */
+    async revokeByRefresh(refreshToken) {
+        const row = await this.db
+            .selectFrom("sessions")
+            .select("id")
+            .where("refresh_hash", "=", sha256Hex(refreshToken))
+            .where("revoked_at", "is", null)
+            .executeTakeFirst();
+        if (row)
+            await this.revoke(row.id);
+    }
+    async revoke(sessionId) {
+        await this.db
+            .updateTable("sessions")
+            .set({ revoked_at: sql `now()` })
+            .where("id", "=", sessionId)
+            .where("revoked_at", "is", null)
+            .execute();
+        await this.redis.set(revokedKey(sessionId), "1", "EX", REVOKED_MARKER_TTL_SECONDS);
+    }
+    async revokeAllForAccount(accountId, exceptSessionId) {
+        let q = this.db
+            .updateTable("sessions")
+            .set({ revoked_at: sql `now()` })
+            .where("account_id", "=", accountId)
+            .where("revoked_at", "is", null);
+        if (exceptSessionId !== undefined)
+            q = q.where("id", "!=", exceptSessionId);
+        const rows = await q.returning("id").execute();
+        await this.markRevoked(rows.map((r) => r.id));
+        return rows.length;
+    }
+    /**
+     * 给已在 PG 中吊销的会话写 Redis 吊销标记（快速路径）；任一写入失败即抛出。
+     * 鉴权以 PG `revoked_at` 为准，调用方可以把这一步当作尽力而为。
+     */
+    async markRevoked(sessionIds) {
+        if (sessionIds.length === 0)
+            return;
+        const pipe = this.redis.pipeline();
+        for (const id of sessionIds)
+            pipe.set(revokedKey(id), "1", "EX", REVOKED_MARKER_TTL_SECONDS);
+        const results = (await pipe.exec()) ?? [];
+        const failed = results.find(([err]) => err);
+        if (failed)
+            throw failed[0];
+    }
+    /** 设当前组织；会话已吊销、已过期或不存在 → `auth.session_revoked`。 */
+    async setCurrentOrg(sessionId, orgId) {
+        const r = await this.db
+            .updateTable("sessions")
+            .set({ current_org_id: orgId })
+            .where("id", "=", sessionId)
+            .where("revoked_at", "is", null)
+            .where("expires_at", ">", sql `now()`)
+            .executeTakeFirst();
+        if (r.numUpdatedRows === 0n) {
+            throw new ApiError("auth.session_revoked", "Session has been revoked");
+        }
+    }
+    /**
+     * 切换当前组织（Web 会话）：同一事务内先 `SELECT … FROM memberships WHERE org_id = $1 AND account_id = $2 FOR SHARE`
+     * 锁住这一条成员关系（且组织未软删除），再写会话——与「移出成员」（DELETE memberships 后清空会话当前组织）互斥，
+     * 不会留下指向已移出组织的 `current_org_id`。非成员或组织已软删除 → `org.not_found`；`null` 清空，不查成员关系。
+     */
+    async switchCurrentOrg(sessionId, accountId, orgId) {
+        if (orgId === null)
+            return this.setCurrentOrg(sessionId, null);
+        await this.db.transaction().execute(async (t) => {
+            // 加锁顺序与移出成员一致：先组织行、再成员关系行（sessions.current_org_id 的外键检查也会锁组织行，
+            // 若先锁成员关系，会与持有组织行锁的移出成员互相等待而死锁）
+            const org = await t
+                .selectFrom("orgs")
+                .select("id")
+                .where("id", "=", orgId)
+                .where("deleted_at", "is", null)
+                .forShare()
+                .executeTakeFirst();
+            const m = org &&
+                (await t
+                    .selectFrom("memberships")
+                    .select("role")
+                    .where("org_id", "=", orgId)
+                    .where("account_id", "=", accountId)
+                    .forShare()
+                    .executeTakeFirst());
+            if (!m)
+                throw new ApiError("org.not_found", "Organization not found");
+            const r = await t
+                .updateTable("sessions")
+                .set({ current_org_id: orgId })
+                .where("id", "=", sessionId)
+                .where("revoked_at", "is", null)
+                .where("expires_at", ">", sql `now()`)
+                .executeTakeFirst();
+            if (r.numUpdatedRows === 0n) {
+                throw new ApiError("auth.session_revoked", "Session has been revoked");
+            }
+        });
+    }
+    /** 有效（未吊销且未过期）的会话；否则返回 undefined。 */
+    async get(sessionId) {
+        const row = await this.db
+            .selectFrom("sessions")
+            .select(["id", "account_id", "current_org_id"])
+            .where("id", "=", sessionId)
+            .where("revoked_at", "is", null)
+            .where("expires_at", ">", sql `now()`)
+            .executeTakeFirst();
+        return row && { id: row.id, accountId: row.account_id, currentOrgId: row.current_org_id };
+    }
+    keyFor = (header) => {
+        const key = header.kid === undefined ? undefined : this.keys.byId(header.kid);
+        if (!key)
+            throw new UnknownKidError("unknown kid");
+        return key;
+    };
+    async issue(sessionId, accountId, refreshToken, refreshExpiresAt) {
+        const iat = Math.floor(Date.now() / 1000);
+        const exp = iat + this.opts.accessTtlSeconds;
+        const accessToken = await new SignJWT({ sid: sessionId })
+            .setProtectedHeader({ alg: "HS256", kid: this.keys.currentId })
+            .setSubject(accountId)
+            .setIssuedAt(iat)
+            .setExpirationTime(exp)
+            .sign(this.keys.current);
+        return {
+            sessionId,
+            accountId,
+            accessToken,
+            refreshToken,
+            accessExpiresAt: new Date(exp * 1000),
+            refreshExpiresAt,
+        };
+    }
+}

package/dist/identity/settings.d.ts

@@ -0,0 +1,121 @@
+import type { Logger } from "@capybara-hq/plugin-sdk";
+import type { Transaction } from "kysely";
+import { z } from "zod";
+import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
+/** 沙箱 cpu（核）与内存（MB）覆盖的范围（C19）。 */
+export declare const SANDBOX_CPU_RANGE: {
+    readonly min: 0.25;
+    readonly max: 64;
+};
+export declare const SANDBOX_MEMORY_MB_RANGE: {
+    readonly min: 256;
+    readonly max: 262144;
+};
+/** 一个组织的沙箱限额覆盖：至少给一项；未给的项用部署默认。 */
+export declare const SANDBOX_LIMIT_OVERRIDE: z.ZodObject<{
+    cpu: z.ZodOptional<z.ZodNumber>;
+    memoryMb: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type SandboxLimitOverride = z.infer<typeof SANDBOX_LIMIT_OVERRIDE>;
+/**
+ * One organization's sub-agent limits (sub-agents spec §8.2): any of the three `subagents.*`
+ * values, within the same bounds; the ones not given use the deployment's config.
+ */
+export declare const SUBAGENT_LIMIT_OVERRIDE: z.ZodObject<{
+    maxConcurrentPerRun: z.ZodOptional<z.ZodNumber>;
+    maxDispatchesPerRun: z.ZodOptional<z.ZodNumber>;
+    maxTokensPerRun: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type SubagentLimitOverride = z.infer<typeof SUBAGENT_LIMIT_OVERRIDE>;
+export declare const DEPLOYMENT_SETTINGS: z.ZodObject<{
+    orgCreation: z.ZodDefault<z.ZodEnum<{
+        anyone: "anyone";
+        enterprise_admin: "enterprise_admin";
+    }>>;
+    runConcurrencyOverrides: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    priceCurrency: z.ZodDefault<z.ZodString>;
+    sandboxLimitOverrides: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        cpu: z.ZodOptional<z.ZodNumber>;
+        memoryMb: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>>;
+    subagentLimitOverrides: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        maxConcurrentPerRun: z.ZodOptional<z.ZodNumber>;
+        maxDispatchesPerRun: z.ZodOptional<z.ZodNumber>;
+        maxTokensPerRun: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>>;
+    customConnectors: z.ZodDefault<z.ZodEnum<{
+        allow: "allow";
+        deny: "deny";
+    }>>;
+    customSkills: z.ZodDefault<z.ZodEnum<{
+        allow: "allow";
+        deny: "deny";
+    }>>;
+}, z.core.$strip>;
+export type DeploymentSettings = z.infer<typeof DEPLOYMENT_SETTINGS>;
+/**
+ * 设置的修改（PUT /api/v1/admin/settings 的 body）：只改给出的键。
+ * `runConcurrencyOverrides` 按组织合并：值为正整数 → 设置该组织的上限；值为 null → 删除该组织的覆盖
+ * （回到 `runtime.orgConcurrency`）；未列出的组织保持不变。
+ * `sandboxLimitOverrides` 同样按组织合并：给出的组织整项替换（未给的 cpu / memoryMb 回到部署默认），null 删除。
+ * `subagentLimitOverrides` merges by organization the same way: a given organization's entry is
+ * replaced whole (values left out go back to `subagents.*`), null removes it.
+ */
+export declare const DEPLOYMENT_SETTINGS_PATCH: z.ZodObject<{
+    orgCreation: z.ZodOptional<z.ZodEnum<{
+        anyone: "anyone";
+        enterprise_admin: "enterprise_admin";
+    }>>;
+    runConcurrencyOverrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodNumber>>>;
+    priceCurrency: z.ZodOptional<z.ZodString>;
+    sandboxLimitOverrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodObject<{
+        cpu: z.ZodOptional<z.ZodNumber>;
+        memoryMb: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>>>;
+    subagentLimitOverrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodObject<{
+        maxConcurrentPerRun: z.ZodOptional<z.ZodNumber>;
+        maxDispatchesPerRun: z.ZodOptional<z.ZodNumber>;
+        maxTokensPerRun: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>>>;
+    customConnectors: z.ZodOptional<z.ZodEnum<{
+        allow: "allow";
+        deny: "deny";
+    }>>;
+    customSkills: z.ZodOptional<z.ZodEnum<{
+        allow: "allow";
+        deny: "deny";
+    }>>;
+}, z.core.$strict>;
+export type DeploymentSettingsPatch = z.infer<typeof DEPLOYMENT_SETTINGS_PATCH>;
+/**
+ * 读某个组织的沙箱限额覆盖（创建沙箱、组织设置页用）；每次实时读 PG，多副本下改动立即生效。
+ * 只解析这个组织的那一条：没有设置、组织不在其中、或这一条存量值非法 → undefined；别的组织的条目非法不影响它。
+ */
+export declare function readSandboxLimitOverride(db: KernelDb, orgId: string): Promise<SandboxLimitOverride | undefined>;
+/**
+ * One organization's sub-agent limit override, read live from PG (so a change applies on every
+ * replica at once); in the caller's transaction when one is given. Only this organization's entry
+ * is parsed: no setting, no entry, or an invalid stored entry → undefined.
+ */
+export declare function readSubagentLimitOverride(db: KernelDb | Transaction<KernelDatabase>, orgId: string): Promise<SubagentLimitOverride | undefined>;
+/**
+ * When orgs may not create their own connectors / skills (deployment setting `customConnectors` /
+ * `customSkills` is `deny`, C22) throws `catalog.custom_disabled`: install from the enterprise
+ * catalog only. Reads PG live every time (can read in the caller's transaction); an invalid stored
+ * value counts as allow.
+ */
+export declare function assertCustomAllowed(db: KernelDb | Transaction<KernelDatabase>, key: "customConnectors" | "customSkills"): Promise<void>;
+/** 部署级设置：每个键一行，读时缺省用默认值。 */
+export declare class SettingsService {
+    private readonly db;
+    private readonly log?;
+    constructor(db: KernelDb, log?: Pick<Logger, "warn"> | undefined);
+    /**
+     * 读全部设置；传 `trx` 时在该事务内读（调用方已持有事务连接时不再占用池里的第二个连接）。
+     * 逐个键校验：库里某个键的值非法时该键用默认值并 warn 点名，其余合法的键照常生效；
+     * 不认识的键（如新版本写入的）忽略。
+     */
+    get(trx?: Transaction<KernelDatabase>): Promise<DeploymentSettings>;
+    /** 更新设置：事务内取企业管理员锁并复核发起人仍是活跃企业管理员（否则 `forbidden`）。 */
+    update(patch: DeploymentSettingsPatch, actorAccountId: string, actorTokenId?: string): Promise<DeploymentSettings>;
+}

package/dist/identity/settings.js

@@ -0,0 +1,248 @@
+import { z } from "zod";
+import { ApiError } from "../errors.js";
+import { audit } from "./audit.js";
+import { lockEnterpriseAdminsAndAuthorize } from "./enterprise-admin.js";
+/** 币种代码：ISO 4217 的三位大写字母（如 USD、CNY）。 */
+const CurrencyCode = z.string().regex(/^[A-Z]{3}$/, "must be a 3-letter ISO 4217 currency code");
+/** 沙箱 cpu（核）与内存（MB）覆盖的范围（C19）。 */
+export const SANDBOX_CPU_RANGE = { min: 0.25, max: 64 };
+export const SANDBOX_MEMORY_MB_RANGE = { min: 256, max: 262_144 };
+/** 一个组织的沙箱限额覆盖：至少给一项；未给的项用部署默认。 */
+export const SANDBOX_LIMIT_OVERRIDE = z
+    .object({
+    cpu: z.number().min(SANDBOX_CPU_RANGE.min).max(SANDBOX_CPU_RANGE.max).optional(),
+    memoryMb: z
+        .number()
+        .int()
+        .min(SANDBOX_MEMORY_MB_RANGE.min)
+        .max(SANDBOX_MEMORY_MB_RANGE.max)
+        .optional(),
+})
+    .strict()
+    .refine((o) => o.cpu !== undefined || o.memoryMb !== undefined, {
+    message: "give cpu, memoryMb or both",
+});
+/**
+ * One organization's sub-agent limits (sub-agents spec §8.2): any of the three `subagents.*`
+ * values, within the same bounds; the ones not given use the deployment's config.
+ */
+export const SUBAGENT_LIMIT_OVERRIDE = z
+    .object({
+    maxConcurrentPerRun: z.number().int().min(1).max(20).optional(),
+    maxDispatchesPerRun: z.number().int().min(1).max(500).optional(),
+    maxTokensPerRun: z.number().int().min(10_000).optional(),
+})
+    .strict()
+    .refine((o) => Object.values(o).some((v) => v !== undefined), {
+    message: "give maxConcurrentPerRun, maxDispatchesPerRun or maxTokensPerRun",
+});
+/** 组织能否自建连接器 / 技能（C22）：`deny` 时只能从企业目录安装（T26 执行）。 */
+const CustomPolicy = z.enum(["allow", "deny"]);
+export const DEPLOYMENT_SETTINGS = z.object({
+    orgCreation: z.enum(["anyone", "enterprise_admin"]).default("anyone"),
+    /** 按组织覆盖运行并发上限（orgId → 上限）；未列出的组织用 `runtime.orgConcurrency`。 */
+    runConcurrencyOverrides: z.record(z.string().min(1), z.number().int().positive()).default({}),
+    /** 模型价格表（`model_prices`）的币种；只用于显示估算成本，不做换算。 */
+    priceCurrency: CurrencyCode.default("USD"),
+    /** 按组织覆盖沙箱 cpu / 内存（orgId → 覆盖，C19）；只对之后新建的沙箱生效。组织管理员只读。 */
+    sandboxLimitOverrides: z.record(z.string().min(1), SANDBOX_LIMIT_OVERRIDE).default({}),
+    /**
+     * Per-organization sub-agent limits (orgId → override); organizations not listed, and values
+     * not given, use `subagents.*`. Read live on every dispatch and tool resolution.
+     */
+    subagentLimitOverrides: z.record(z.string().min(1), SUBAGENT_LIMIT_OVERRIDE).default({}),
+    /** 组织能否自建连接器（不经企业目录）。 */
+    customConnectors: CustomPolicy.default("allow"),
+    /**
+     * 组织能否自建技能（不经企业目录）：deny 时组织管理员不能上传技能包。agent 自写技能（`skill_write`，私有 agent 的
+     * agent 级技能与共享 agent 经负责人审批的变更）不受此开关约束——那是 agent 定义的一部分，由 R3 / R4 把关。
+     */
+    customSkills: CustomPolicy.default("allow"),
+});
+const DEFAULTS = DEPLOYMENT_SETTINGS.parse({});
+/**
+ * 设置的修改（PUT /api/v1/admin/settings 的 body）：只改给出的键。
+ * `runConcurrencyOverrides` 按组织合并：值为正整数 → 设置该组织的上限；值为 null → 删除该组织的覆盖
+ * （回到 `runtime.orgConcurrency`）；未列出的组织保持不变。
+ * `sandboxLimitOverrides` 同样按组织合并：给出的组织整项替换（未给的 cpu / memoryMb 回到部署默认），null 删除。
+ * `subagentLimitOverrides` merges by organization the same way: a given organization's entry is
+ * replaced whole (values left out go back to `subagents.*`), null removes it.
+ */
+export const DEPLOYMENT_SETTINGS_PATCH = z
+    .object({
+    orgCreation: z.enum(["anyone", "enterprise_admin"]).optional(),
+    runConcurrencyOverrides: z
+        .record(z.string().min(1), z.number().int().positive().nullable())
+        .optional(),
+    priceCurrency: CurrencyCode.optional(),
+    sandboxLimitOverrides: z
+        .record(z.string().min(1), SANDBOX_LIMIT_OVERRIDE.nullable())
+        .optional(),
+    subagentLimitOverrides: z
+        .record(z.string().min(1), SUBAGENT_LIMIT_OVERRIDE.nullable())
+        .optional(),
+    customConnectors: CustomPolicy.optional(),
+    customSkills: CustomPolicy.optional(),
+})
+    .strict();
+/**
+ * 读某个组织的沙箱限额覆盖（创建沙箱、组织设置页用）；每次实时读 PG，多副本下改动立即生效。
+ * 只解析这个组织的那一条：没有设置、组织不在其中、或这一条存量值非法 → undefined；别的组织的条目非法不影响它。
+ */
+export async function readSandboxLimitOverride(db, orgId) {
+    const row = await db
+        .selectFrom("deployment_settings")
+        .select("value")
+        .where("key", "=", "sandboxLimitOverrides")
+        .executeTakeFirst();
+    if (!row)
+        return undefined;
+    const all = row.value;
+    if (typeof all !== "object" || all === null || Array.isArray(all) || !Object.hasOwn(all, orgId)) {
+        return undefined;
+    }
+    const parsed = SANDBOX_LIMIT_OVERRIDE.safeParse(all[orgId]);
+    return parsed.success ? parsed.data : undefined;
+}
+/**
+ * One organization's sub-agent limit override, read live from PG (so a change applies on every
+ * replica at once); in the caller's transaction when one is given. Only this organization's entry
+ * is parsed: no setting, no entry, or an invalid stored entry → undefined.
+ */
+export async function readSubagentLimitOverride(db, orgId) {
+    const row = await db
+        .selectFrom("deployment_settings")
+        .select("value")
+        .where("key", "=", "subagentLimitOverrides")
+        .executeTakeFirst();
+    if (!row)
+        return undefined;
+    const all = row.value;
+    if (typeof all !== "object" || all === null || Array.isArray(all) || !Object.hasOwn(all, orgId)) {
+        return undefined;
+    }
+    const parsed = SUBAGENT_LIMIT_OVERRIDE.safeParse(all[orgId]);
+    return parsed.success ? parsed.data : undefined;
+}
+/**
+ * When orgs may not create their own connectors / skills (deployment setting `customConnectors` /
+ * `customSkills` is `deny`, C22) throws `catalog.custom_disabled`: install from the enterprise
+ * catalog only. Reads PG live every time (can read in the caller's transaction); an invalid stored
+ * value counts as allow.
+ */
+export async function assertCustomAllowed(db, key) {
+    const row = await db
+        .selectFrom("deployment_settings")
+        .select("value")
+        .where("key", "=", key)
+        .executeTakeFirst();
+    if (!row)
+        return;
+    const parsed = CustomPolicy.safeParse(row.value);
+    if (parsed.success && parsed.data === "deny") {
+        throw new ApiError("catalog.custom_disabled", key === "customConnectors"
+            ? "Custom connectors are disabled in this deployment; install connectors from the enterprise catalog"
+            : "Custom skills are disabled in this deployment; install skills from the enterprise catalog");
+    }
+}
+/** 按组织合并覆盖：值为 null 删除该组织，其余整项替换；未列出的组织不变。 */
+function mergeByOrg(current, patch) {
+    const merged = { ...current };
+    for (const [orgId, value] of Object.entries(patch)) {
+        if (value === null)
+            delete merged[orgId];
+        else
+            merged[orgId] = value;
+    }
+    return merged;
+}
+/** 部署级设置：每个键一行，读时缺省用默认值。 */
+export class SettingsService {
+    db;
+    log;
+    constructor(db, log) {
+        this.db = db;
+        this.log = log;
+    }
+    /**
+     * 读全部设置；传 `trx` 时在该事务内读（调用方已持有事务连接时不再占用池里的第二个连接）。
+     * 逐个键校验：库里某个键的值非法时该键用默认值并 warn 点名，其余合法的键照常生效；
+     * 不认识的键（如新版本写入的）忽略。
+     */
+    async get(trx) {
+        const rows = await (trx ?? this.db)
+            .selectFrom("deployment_settings")
+            .select(["key", "value"])
+            .execute();
+        const stored = new Map(rows.map((r) => [r.key, r.value]));
+        const out = { ...DEFAULTS };
+        for (const [key, field] of Object.entries(DEPLOYMENT_SETTINGS.shape)) {
+            if (!stored.has(key))
+                continue;
+            const parsed = field.safeParse(stored.get(key));
+            if (parsed.success) {
+                out[key] = parsed.data;
+            }
+            else {
+                this.log?.warn("invalid deployment setting; using default", {
+                    key,
+                    issues: parsed.error.issues.map((i) => i.message),
+                });
+            }
+        }
+        return out;
+    }
+    /** 更新设置：事务内取企业管理员锁并复核发起人仍是活跃企业管理员（否则 `forbidden`）。 */
+    async update(patch, actorAccountId, actorTokenId) {
+        const check = DEPLOYMENT_SETTINGS_PATCH.safeParse(patch);
+        if (!check.success) {
+            throw new ApiError("validation_failed", "Invalid deployment settings", check.error.issues.map((i) => ({ path: i.path.join("."), message: i.message })));
+        }
+        await this.db.transaction().execute(async (trx) => {
+            await lockEnterpriseAdminsAndAuthorize(trx, actorAccountId);
+            // 企业管理员锁串行化所有设置修改：在锁内读当前覆盖再合并，不会丢失并发修改。
+            const next = {};
+            if (check.data.orgCreation !== undefined)
+                next.orgCreation = check.data.orgCreation;
+            if (check.data.priceCurrency !== undefined)
+                next.priceCurrency = check.data.priceCurrency;
+            if (check.data.customConnectors !== undefined) {
+                next.customConnectors = check.data.customConnectors;
+            }
+            if (check.data.customSkills !== undefined)
+                next.customSkills = check.data.customSkills;
+            const { runConcurrencyOverrides: runPatch, sandboxLimitOverrides: sandboxPatch, subagentLimitOverrides: subagentPatch, } = check.data;
+            if (runPatch !== undefined || sandboxPatch !== undefined || subagentPatch !== undefined) {
+                const current = await this.get(trx);
+                if (runPatch !== undefined) {
+                    next.runConcurrencyOverrides = mergeByOrg(current.runConcurrencyOverrides, runPatch);
+                }
+                if (sandboxPatch !== undefined) {
+                    next.sandboxLimitOverrides = mergeByOrg(current.sandboxLimitOverrides, sandboxPatch);
+                }
+                if (subagentPatch !== undefined) {
+                    next.subagentLimitOverrides = mergeByOrg(current.subagentLimitOverrides, subagentPatch);
+                }
+            }
+            for (const [key, value] of Object.entries(next)) {
+                if (value === undefined)
+                    continue;
+                const json = JSON.stringify(value);
+                await trx
+                    .insertInto("deployment_settings")
+                    .values({ key, value: json, updated_by: actorAccountId })
+                    .onConflict((oc) => oc
+                    .column("key")
+                    .doUpdateSet({ value: json, updated_by: actorAccountId, updated_at: new Date() }))
+                    .execute();
+            }
+            await audit(trx, {
+                actorAccountId,
+                ...(actorTokenId !== undefined && { actorTokenId }),
+                action: "deployment.settings.updated",
+                detail: check.data,
+            });
+        });
+        return this.get();
+    }
+}