@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.20

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

@@ -0,0 +1,24 @@
+import { z } from "zod";
+import type { RouteSchemas } from "../platform/route-schemas.js";
+/**
+ * `PUT /me/preferences`: a partial update of the person's preferences; a field left out keeps its
+ * stored value (themes spec §9).
+ */
+export declare const PreferencesSchema: z.ZodObject<{
+    timeZone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    theme: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+/** The person's preferences as `GET` / `PUT /me/preferences` return them. */
+export interface Preferences {
+    timeZone: string | null;
+    theme: string | null;
+}
+declare const PreferencesBody_base: import("../infra/validation/create-zod-dto.js").ZodDtoClass<z.ZodObject<{
+    timeZone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    theme: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>>;
+export declare class PreferencesBody extends PreferencesBody_base {
+}
+/** The `/me` routes the Platform operations mirror (`check:platform-ops` keys). */
+export declare const ME_ROUTES: readonly RouteSchemas[];
+export {};

package/dist/identity/me.schemas.js

@@ -0,0 +1,25 @@
+import { z } from "zod";
+import { createZodDto } from "../infra/validation/create-zod-dto.js";
+import { IanaTimeZone } from "../time-zone.js";
+/**
+ * `PUT /me/preferences`: a partial update of the person's preferences; a field left out keeps its
+ * stored value (themes spec §9).
+ */
+export const PreferencesSchema = z
+    .object({
+    /** The person's time zone (IANA); null = follow the browser (run context spec §3.4). */
+    timeZone: IanaTimeZone.nullable().optional(),
+    /**
+     * The person's theme (a `platform_themes` id on in at least one of their orgs, else 400
+     * `theme.not_available`); null = follow the org (themes spec §7).
+     */
+    theme: z.string().min(1).max(200).nullable().optional(),
+})
+    .strict();
+export class PreferencesBody extends createZodDto(PreferencesSchema, "PreferencesBody") {
+}
+/** The `/me` routes the Platform operations mirror (`check:platform-ops` keys). */
+export const ME_ROUTES = [
+    { route: "GET /api/v1/me/preferences" },
+    { route: "PUT /api/v1/me/preferences", body: PreferencesSchema },
+];

package/dist/identity/principal.d.ts

@@ -28,8 +28,9 @@ declare module "fastify" {
 }
 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 SUPER_ADMIN_KEY = "capybara:auth:super-admin";
 export declare const ALLOW_SERVICE_KEY = "capybara:auth:allow-service";
+export declare const PASSWORD_CHANGE_KEY = "capybara:auth:password-change";
 /**
  * 不要求凭据：无凭据时放行（principal 为 undefined）；带了有效凭据仍解析，无效凭据按无凭据处理。
  * 非安全方法照样要求 `X-Capybara-Csrf: 1`（防登录 CSRF）。新增公开路由必须同时更新 public-routes 元测试的清单。
@@ -37,8 +38,15 @@ export declare const ALLOW_SERVICE_KEY = "capybara:auth:allow-service";
 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;
+/** 仅超级管理员（user principal 且 `isSuperAdmin`）；否则 `forbidden`。 */
+export declare const SuperAdmin: () => MethodDecorator & ClassDecorator;
+/**
+ * Reachable by an account that must change its generated initial password first
+ * (`Account.mustChangePassword`): the guard refuses every other route with
+ * `auth.password_change_required`. Only `GET /me` and `PUT /me/password` carry it (public routes
+ * such as logout are reachable anyway).
+ */
+export declare const AllowPendingPasswordChange: () => MethodDecorator;
 /**
  * 允许服务令牌（service principal）访问。默认拒绝：未标注的路由只接受 user principal，service → `forbidden`。
  * 组织级路由由 OrgGuard 再核对令牌所属组织与角色。

package/dist/identity/principal.js

@@ -2,8 +2,9 @@ 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 SUPER_ADMIN_KEY = "capybara:auth:super-admin";
 export const ALLOW_SERVICE_KEY = "capybara:auth:allow-service";
+export const PASSWORD_CHANGE_KEY = "capybara:auth:password-change";
 /**
  * 不要求凭据：无凭据时放行（principal 为 undefined）；带了有效凭据仍解析，无效凭据按无凭据处理。
  * 非安全方法照样要求 `X-Capybara-Csrf: 1`（防登录 CSRF）。新增公开路由必须同时更新 public-routes 元测试的清单。
@@ -11,8 +12,15 @@ export const ALLOW_SERVICE_KEY = "capybara:auth:allow-service";
 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);
+/** 仅超级管理员（user principal 且 `isSuperAdmin`）；否则 `forbidden`。 */
+export const SuperAdmin = () => SetMetadata(SUPER_ADMIN_KEY, true);
+/**
+ * Reachable by an account that must change its generated initial password first
+ * (`Account.mustChangePassword`): the guard refuses every other route with
+ * `auth.password_change_required`. Only `GET /me` and `PUT /me/password` carry it (public routes
+ * such as logout are reachable anyway).
+ */
+export const AllowPendingPasswordChange = () => SetMetadata(PASSWORD_CHANGE_KEY, true);
 /**
  * 允许服务令牌（service principal）访问。默认拒绝：未标注的路由只接受 user principal，service → `forbidden`。
  * 组织级路由由 OrgGuard 再核对令牌所属组织与角色。

package/dist/identity/sessions.d.ts

@@ -36,6 +36,18 @@ export declare class SessionService {
         userAgent?: string;
         ip?: string;
     }): Promise<IssuedSession>;
+    /**
+     * The org a new session starts in: the account's last chosen one while it is still a member of it
+     * (and the org is not deleted), else its only org when it has exactly one, else none (the web
+     * app then asks to choose or create one).
+     */
+    private startingOrg;
+    /**
+     * Read-only: of several refresh tokens (a cookie header carrying the legacy and the `Path=/`
+     * cookie), the first that is the current token of a live session, if any. Choosing before
+     * rotating keeps a stale token from tripping replay detection on a still valid session.
+     */
+    pickCurrentRefresh(candidates: readonly string[]): Promise<string | undefined>;
     refresh(refreshToken: string, meta: {
         userAgent?: string;
         ip?: string;

package/dist/identity/sessions.js

@@ -72,11 +72,49 @@ let SessionService = class SessionService {
             user_agent: meta.userAgent ?? null,
             ip: meta.ip ?? null,
             expires_at: sql `now() + make_interval(days => ${refreshTtlDays})`,
+            current_org_id: await this.startingOrg(accountId),
         })
             .returning(["expires_at"])
             .executeTakeFirstOrThrow();
         return this.issue(id, accountId, refreshToken, row.expires_at);
     }
+    /**
+     * The org a new session starts in: the account's last chosen one while it is still a member of it
+     * (and the org is not deleted), else its only org when it has exactly one, else none (the web
+     * app then asks to choose or create one).
+     */
+    async startingOrg(accountId) {
+        const orgs = await this.db
+            .selectFrom("memberships as m")
+            .innerJoin("orgs as o", "o.id", "m.org_id")
+            .innerJoin("accounts as a", "a.id", "m.account_id")
+            .select(["m.org_id as orgId", "a.last_org_id as lastOrgId"])
+            .where("m.account_id", "=", accountId)
+            .where("o.deleted_at", "is", null)
+            .execute();
+        const last = orgs.find((o) => o.orgId === o.lastOrgId);
+        if (last)
+            return last.orgId;
+        return orgs.length === 1 ? (orgs[0]?.orgId ?? null) : null;
+    }
+    /**
+     * Read-only: of several refresh tokens (a cookie header carrying the legacy and the `Path=/`
+     * cookie), the first that is the current token of a live session, if any. Choosing before
+     * rotating keeps a stale token from tripping replay detection on a still valid session.
+     */
+    async pickCurrentRefresh(candidates) {
+        if (candidates.length === 0)
+            return undefined;
+        const rows = await this.db
+            .selectFrom("sessions")
+            .select("refresh_hash")
+            .where("refresh_hash", "in", candidates.map((c) => sha256Hex(c)))
+            .where("revoked_at", "is", null)
+            .where("expires_at", ">", sql `now()`)
+            .execute();
+        const live = new Set(rows.map((r) => r.refresh_hash));
+        return candidates.find((c) => live.has(sha256Hex(c)));
+    }
     async refresh(refreshToken, meta) {
         const oldHash = sha256Hex(refreshToken);
         const next = newRefreshToken();
@@ -277,6 +315,13 @@ let SessionService = class SessionService {
                 .executeTakeFirst());
         if (!m)
             throw new ApiError("org.not_found", "Organization not found");
+        // remembered for the next sign-in; the account row before the session row, the order a
+        // password change takes (account, then its sessions)
+        await this.db
+            .updateTable("accounts")
+            .set({ last_org_id: orgId })
+            .where("id", "=", accountId)
+            .execute();
         const r = await this.db
             .updateTable("sessions")
             .set({ current_org_id: orgId })

package/dist/identity/settings.d.ts

@@ -3,7 +3,8 @@ import type { KernelSchemaDb } from "../db/kernel-schema.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import type { KernelLogger } from "../log.js";
-import { EnterpriseAdminLock } from "./enterprise-admin.js";
+import { type UiArrangement } from "../ui/arrangement.js";
+import { SuperAdminLock } from "./super-admin.js";
 /** 沙箱 cpu（核）与内存（MB）覆盖的范围（C19）。 */
 export declare const SANDBOX_CPU_RANGE: {
     readonly min: 0.25;
@@ -20,19 +21,58 @@ export declare const SANDBOX_LIMIT_OVERRIDE: z.ZodObject<{
 }, 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.
+ * One organization's sub-agent limits (sub-agents spec §8.2, agent map spec §6): any of the
+ * `subagents.*` values, within the same bounds (0 for dispatches or tokens: no limit); the ones not
+ * given use the deployment's config.
  */
 export declare const SUBAGENT_LIMIT_OVERRIDE: z.ZodObject<{
-    maxConcurrentPerRun: z.ZodOptional<z.ZodNumber>;
+    maxDepth: z.ZodOptional<z.ZodNumber>;
+    maxConcurrentPerConversation: 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>;
+/** The deployment setting key of the platform default theme (themes spec §7). */
+export declare const UI_THEME_SETTING = "uiTheme";
+/**
+ * The platform default theme (themes spec §7): a `platform_themes` id, or null for the built-in
+ * theme. Only a platform-owned theme whose effective scope is `all` can be set (checked by
+ * {@link SettingsService.update}); every reader goes through {@link readUiTheme} or
+ * {@link SettingsService.get}, both parsing with this schema.
+ */
+export declare const UiThemeSetting: z.ZodObject<{
+    id: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type UiTheme = z.infer<typeof UiThemeSetting>;
+/** The deployment setting key of the client code kill switch (client extensions spec §10.2). */
+export declare const CLIENT_EXTENSIONS_SETTING = "clientExtensions";
+/** The plugins listed in `clientExtensions.disabled`: at most this many. */
+export declare const CLIENT_DISABLED_MAX = 200;
+/**
+ * The client code kill switch (client extensions spec §10.2): `enabled: false` stops every plugin's
+ * client code (the shell reads list nothing, delivery is 404); `disabled` names the plugins whose
+ * client code alone is stopped while their server side keeps running. Every reader goes through
+ * {@link readClientExtensions} or {@link SettingsService.get}.
+ */
+export declare const ClientExtensionsSetting: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    disabled: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type ClientExtensionsKillSwitch = z.infer<typeof ClientExtensionsSetting>;
+/** The kill switch's default (and what a missing or invalid stored value reads as): everything on. */
+export declare const clientExtensionsDefault: () => ClientExtensionsKillSwitch;
+/**
+ * Parses a stored `clientExtensions` value (the `deployment_settings` row's `value`, undefined when
+ * the row is missing): the default when missing; when invalid the default too, with a warning naming
+ * the key (a kill switch that fails open is worth a log line, as {@link SettingsService.get} logs
+ * every other invalid key). The one parser of the setting: the settings service and every access
+ * check read through it.
+ */
+export declare function parseClientExtensions(value: unknown, log?: Pick<KernelLogger, "warn">): ClientExtensionsKillSwitch;
 export declare const DEPLOYMENT_SETTINGS: z.ZodObject<{
     orgCreation: z.ZodDefault<z.ZodEnum<{
         anyone: "anyone";
-        enterprise_admin: "enterprise_admin";
+        super_admin: "super_admin";
     }>>;
     runConcurrencyOverrides: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodNumber>>;
     priceCurrency: z.ZodDefault<z.ZodString>;
@@ -41,7 +81,8 @@ export declare const DEPLOYMENT_SETTINGS: z.ZodObject<{
         memoryMb: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>>;
     subagentLimitOverrides: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
-        maxConcurrentPerRun: z.ZodOptional<z.ZodNumber>;
+        maxDepth: z.ZodOptional<z.ZodNumber>;
+        maxConcurrentPerConversation: z.ZodOptional<z.ZodNumber>;
         maxDispatchesPerRun: z.ZodOptional<z.ZodNumber>;
         maxTokensPerRun: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>>;
@@ -53,6 +94,15 @@ export declare const DEPLOYMENT_SETTINGS: z.ZodObject<{
         allow: "allow";
         deny: "deny";
     }>>;
+    orgMarketplaceBrowse: z.ZodDefault<z.ZodBoolean>;
+    uiTheme: z.ZodDefault<z.ZodObject<{
+        id: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    uiArrangement: z.ZodDefault<z.ZodType<Partial<Record<"agent.detail.section" | "conversation.composer.frame" | "conversation.empty" | "conversation.panel" | "conversation.properties.section" | "conversation.tool-result.card" | "file.preview" | "org.page" | "org.settings.section" | "platform.page" | "shell.brand" | "shell.overlay", import("../ui/arrangement.js").UiArrangementEntry>>, unknown, z.core.$ZodTypeInternals<Partial<Record<"agent.detail.section" | "conversation.composer.frame" | "conversation.empty" | "conversation.panel" | "conversation.properties.section" | "conversation.tool-result.card" | "file.preview" | "org.page" | "org.settings.section" | "platform.page" | "shell.brand" | "shell.overlay", import("../ui/arrangement.js").UiArrangementEntry>>, unknown>>>;
+    clientExtensions: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        disabled: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type DeploymentSettings = z.infer<typeof DEPLOYMENT_SETTINGS>;
 /**
@@ -66,7 +116,7 @@ export type DeploymentSettings = z.infer<typeof DEPLOYMENT_SETTINGS>;
 export declare const DEPLOYMENT_SETTINGS_PATCH: z.ZodObject<{
     orgCreation: z.ZodOptional<z.ZodEnum<{
         anyone: "anyone";
-        enterprise_admin: "enterprise_admin";
+        super_admin: "super_admin";
     }>>;
     runConcurrencyOverrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodNumber>>>;
     priceCurrency: z.ZodOptional<z.ZodString>;
@@ -75,7 +125,8 @@ export declare const DEPLOYMENT_SETTINGS_PATCH: z.ZodObject<{
         memoryMb: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>>>;
     subagentLimitOverrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodObject<{
-        maxConcurrentPerRun: z.ZodOptional<z.ZodNumber>;
+        maxDepth: z.ZodOptional<z.ZodNumber>;
+        maxConcurrentPerConversation: z.ZodOptional<z.ZodNumber>;
         maxDispatchesPerRun: z.ZodOptional<z.ZodNumber>;
         maxTokensPerRun: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>>>;
@@ -87,6 +138,15 @@ export declare const DEPLOYMENT_SETTINGS_PATCH: z.ZodObject<{
         allow: "allow";
         deny: "deny";
     }>>;
+    orgMarketplaceBrowse: z.ZodOptional<z.ZodBoolean>;
+    uiTheme: z.ZodOptional<z.ZodObject<{
+        id: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+    uiArrangement: z.ZodOptional<z.ZodType<Partial<Record<"agent.detail.section" | "conversation.composer.frame" | "conversation.empty" | "conversation.panel" | "conversation.properties.section" | "conversation.tool-result.card" | "file.preview" | "org.page" | "org.settings.section" | "platform.page" | "shell.brand" | "shell.overlay", import("../ui/arrangement.js").UiArrangementEntry | null>>, unknown, z.core.$ZodTypeInternals<Partial<Record<"agent.detail.section" | "conversation.composer.frame" | "conversation.empty" | "conversation.panel" | "conversation.properties.section" | "conversation.tool-result.card" | "file.preview" | "org.page" | "org.settings.section" | "platform.page" | "shell.brand" | "shell.overlay", import("../ui/arrangement.js").UiArrangementEntry | null>>, unknown>>>;
+    clientExtensions: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        disabled: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 export type DeploymentSettingsPatch = z.infer<typeof DEPLOYMENT_SETTINGS_PATCH>;
 /**
@@ -102,18 +162,43 @@ export declare function readSandboxLimitOverride(db: KernelSchemaDb, orgId: stri
 export declare function readSubagentLimitOverride(db: KernelSchemaDb, 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
+ * `customSkills` is `deny`, C22) throws `catalog.custom_disabled`: install from the platform
  * 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: KernelSchemaDb, key: "customConnectors" | "customSkills"): Promise<void>;
+/**
+ * The deployment setting `orgMarketplaceBrowse`, read live from PG (in the caller's transaction
+ * when there is one); missing or invalid -> the default, true.
+ */
+export declare function readOrgMarketplaceBrowse(db: KernelSchemaDb): Promise<boolean>;
+/**
+ * The platform default theme setting, read live from PG (in the caller's transaction when there is
+ * one) and parsed with {@link UiThemeSetting}: missing or invalid -> `{ id: null }`. `lock`: the
+ * row is read FOR SHARE, so a concurrent write of the setting (which holds it FOR UPDATE) waits for
+ * the caller's transaction, and the reverse.
+ */
+export declare function readUiTheme(db: KernelSchemaDb, opts?: {
+    lock?: boolean;
+}): Promise<UiTheme>;
+/**
+ * The platform default arrangement of UI slots, read live (the lists apply it). An invalid
+ * stored value reads as `{}` (the same fallback {@link SettingsService.get} uses).
+ */
+export declare function readUiArrangement(db: KernelSchemaDb): Promise<UiArrangement>;
+/**
+ * The client code kill switch, read live from PG on every request (in the caller's transaction when
+ * there is one; never cached: every replica sees a change at once), through
+ * {@link parseClientExtensions} (missing or invalid -> everything on; invalid also warns on `log`).
+ */
+export declare function readClientExtensions(db: KernelSchemaDb, log?: Pick<KernelLogger, "warn">): Promise<ClientExtensionsKillSwitch>;
 /** Deployment settings: one row per key, defaults for missing keys. */
 export declare class SettingsService {
     private readonly db;
     readonly txHost: TransactionHost;
     private readonly adminLock;
     private readonly log;
-    constructor(db: KernelDb, txHost: TransactionHost, adminLock: EnterpriseAdminLock, log: Pick<KernelLogger, "warn">);
+    constructor(db: KernelDb, txHost: TransactionHost, adminLock: SuperAdminLock, log: Pick<KernelLogger, "warn">);
     /**
      * Reads every setting, in the context's transaction when there is one (a caller holding a
      * transaction connection does not take a second one from the pool). Each key is validated on
@@ -121,7 +206,9 @@ export declare class SettingsService {
      * valid keys apply; unknown keys (written by a newer version) are ignored.
      */
     get(): Promise<DeploymentSettings>;
-    /** Updates settings under the enterprise admin lock, re-checking the actor (else `forbidden`). */
-    update(patch: DeploymentSettingsPatch, actorAccountId: string, actorTokenId?: string): Promise<DeploymentSettings>;
+    /** Updates settings under the super admin lock, re-checking the actor (else `forbidden`). */
+    update(patch: DeploymentSettingsPatch, actorAccountId: string, actorTokenId?: string, 
+    /** Merged into the audit detail (the Platform tool's `via: "agent"`). */
+    auditDetail?: Record<string, unknown>): Promise<DeploymentSettings>;
     private write;
 }