@sema-agent/settings-schema 10.1.1 → 11.0.0

package/dist/api/feedback.d.ts

@@ -0,0 +1,87 @@
+/**
+ * `api/feedback` —— 壳的 /bug 报告送到 web-admin 的 wire 契约:`POST {web-admin}` + {@link FEEDBACK_V1_PATH} 的请求体
+ * ({@link FeedbackSubmitRequest})、一行报告的回体({@link FeedbackWire})与列表回体。写方(壳)按请求体铸、读方(web-admin)按同一只
+ * schema 判;两个上限一处定义。
+ *
+ *  · 身份(`principal`)**不是**体字段:它恒取访问令牌的主体;体里带了也被剥掉(默认 strip)。
+ *  · `datetime` 是客户端自报的时刻,只作参考 —— 回体的 `createdAt` 由服务端盖。
+ *  · 上界:`description`({@link FEEDBACK_DESCRIPTION_MAX_CHARS})与 `transcript` 的序列化长度({@link FEEDBACK_TRANSCRIPT_MAX_JSON_CHARS})。
+ *    其余附件格 —— `rawTranscriptJsonl` / `subagentTranscripts` / `lastApiRequest` / `errors` —— 本契约**不设上界**,整份请求体也没有;
+ *    `transcript` 一格的上限不是存储的上界,读方要限总量须在自己的入口另设(与写方的长会话附件量一起定)。
+ *
+ * 纯 zod 契约,零 IO,browser-safe。
+ */
+import { z } from "zod";
+/** 报告的端点,相对 web-admin 根。 */
+export declare const FEEDBACK_V1_PATH = "/api/v1/feedback";
+/** `description`(去首尾空白后)的上限 —— 报告常带粘贴的报错与栈,所以宽,但有界。 */
+export declare const FEEDBACK_DESCRIPTION_MAX_CHARS = 20000;
+/** `transcript` 的 JSON 序列化长度上限。 */
+export declare const FEEDBACK_TRANSCRIPT_MAX_JSON_CHARS = 2000000;
+/** /bug 报告的 POST 体(写方铸、读方判,同一只)。 */
+export declare const FeedbackSubmitRequest: z.ZodObject<{
+    surface: z.ZodString;
+    description: z.ZodString;
+    platform: z.ZodString;
+    terminal: z.ZodString;
+    gitRepo: z.ZodBoolean;
+    version: z.ZodString;
+    message_count: z.ZodNumber;
+    datetime: z.ZodString;
+    latestAssistantMessageId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    transcript: z.ZodArray<z.ZodUnknown>;
+    errors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        error: z.ZodOptional<z.ZodString>;
+        timestamp: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    lastApiRequest: z.ZodOptional<z.ZodUnknown>;
+    subagentTranscripts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    rawTranscriptJsonl: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type FeedbackSubmitRequest = z.infer<typeof FeedbackSubmitRequest>;
+/** 一行报告的回体(`POST` 的 201 体、`GET` 列表的一员)。`principal` = 提交者令牌的主体;`createdAt` = 服务端时刻(epoch ms)。 */
+export declare const FeedbackWire: z.ZodObject<{
+    id: z.ZodString;
+    principal: z.ZodString;
+    surface: z.ZodString;
+    description: z.ZodString;
+    platform: z.ZodString;
+    terminal: z.ZodString;
+    gitRepo: z.ZodBoolean;
+    version: z.ZodString;
+    messageCount: z.ZodNumber;
+    latestAssistantMessageId: z.ZodNullable<z.ZodString>;
+    transcript: z.ZodArray<z.ZodUnknown>;
+    errors: z.ZodNullable<z.ZodArray<z.ZodObject<{
+        error: z.ZodOptional<z.ZodString>;
+        timestamp: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    subagentTranscripts: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    hasRawTranscript: z.ZodBoolean;
+    createdAt: z.ZodNumber;
+}, z.core.$strip>;
+export type FeedbackWire = z.infer<typeof FeedbackWire>;
+/** `GET` 的回体(管理员浏览队列)。 */
+export declare const FeedbackListResponse: z.ZodObject<{
+    feedback: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        principal: z.ZodString;
+        surface: z.ZodString;
+        description: z.ZodString;
+        platform: z.ZodString;
+        terminal: z.ZodString;
+        gitRepo: z.ZodBoolean;
+        version: z.ZodString;
+        messageCount: z.ZodNumber;
+        latestAssistantMessageId: z.ZodNullable<z.ZodString>;
+        transcript: z.ZodArray<z.ZodUnknown>;
+        errors: z.ZodNullable<z.ZodArray<z.ZodObject<{
+            error: z.ZodOptional<z.ZodString>;
+            timestamp: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        subagentTranscripts: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        hasRawTranscript: z.ZodBoolean;
+        createdAt: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type FeedbackListResponse = z.infer<typeof FeedbackListResponse>;

package/dist/api/feedback.js

@@ -0,0 +1,66 @@
+/**
+ * `api/feedback` —— 壳的 /bug 报告送到 web-admin 的 wire 契约:`POST {web-admin}` + {@link FEEDBACK_V1_PATH} 的请求体
+ * ({@link FeedbackSubmitRequest})、一行报告的回体({@link FeedbackWire})与列表回体。写方(壳)按请求体铸、读方(web-admin)按同一只
+ * schema 判;两个上限一处定义。
+ *
+ *  · 身份(`principal`)**不是**体字段:它恒取访问令牌的主体;体里带了也被剥掉(默认 strip)。
+ *  · `datetime` 是客户端自报的时刻,只作参考 —— 回体的 `createdAt` 由服务端盖。
+ *  · 上界:`description`({@link FEEDBACK_DESCRIPTION_MAX_CHARS})与 `transcript` 的序列化长度({@link FEEDBACK_TRANSCRIPT_MAX_JSON_CHARS})。
+ *    其余附件格 —— `rawTranscriptJsonl` / `subagentTranscripts` / `lastApiRequest` / `errors` —— 本契约**不设上界**,整份请求体也没有;
+ *    `transcript` 一格的上限不是存储的上界,读方要限总量须在自己的入口另设(与写方的长会话附件量一起定)。
+ *
+ * 纯 zod 契约,零 IO,browser-safe。
+ */
+import { z } from "zod";
+import { INTEGER } from "../integer.js";
+/** 报告的端点,相对 web-admin 根。 */
+export const FEEDBACK_V1_PATH = "/api/v1/feedback";
+/** `description`(去首尾空白后)的上限 —— 报告常带粘贴的报错与栈,所以宽,但有界。 */
+export const FEEDBACK_DESCRIPTION_MAX_CHARS = 20_000;
+/** `transcript` 的 JSON 序列化长度上限。 */
+export const FEEDBACK_TRANSCRIPT_MAX_JSON_CHARS = 2_000_000;
+/** 壳报告的一条错误。 */
+const FeedbackError = z.object({ error: z.string().optional(), timestamp: z.string().optional() });
+/** /bug 报告的 POST 体(写方铸、读方判,同一只)。 */
+export const FeedbackSubmitRequest = z.object({
+    /** 报告从哪个界面发起(壳恒写 `cli`)。 */
+    surface: z.string().min(1),
+    description: z.string().trim().min(1).max(FEEDBACK_DESCRIPTION_MAX_CHARS),
+    platform: z.string(),
+    terminal: z.string(),
+    /** 报告时是否在 git 仓里。 */
+    gitRepo: z.boolean(),
+    /** 发报告的壳的版本。 */
+    version: z.string(),
+    message_count: INTEGER.nonnegative(),
+    /** 客户端自报的时刻(参考,不信任 —— 回体的 `createdAt` 由服务端盖)。 */
+    datetime: z.string(),
+    latestAssistantMessageId: z.string().nullable().optional(),
+    transcript: z.array(z.unknown()).refine((t) => JSON.stringify(t).length <= FEEDBACK_TRANSCRIPT_MAX_JSON_CHARS, {
+        message: `transcript must serialize to at most ${FEEDBACK_TRANSCRIPT_MAX_JSON_CHARS} characters`,
+    }),
+    errors: z.array(FeedbackError).optional(),
+    lastApiRequest: z.unknown().optional(),
+    subagentTranscripts: z.record(z.string(), z.unknown()).optional(),
+    rawTranscriptJsonl: z.string().optional(),
+});
+/** 一行报告的回体(`POST` 的 201 体、`GET` 列表的一员)。`principal` = 提交者令牌的主体;`createdAt` = 服务端时刻(epoch ms)。 */
+export const FeedbackWire = z.object({
+    id: z.string().min(1),
+    principal: z.string().min(1),
+    surface: z.string(),
+    description: z.string(),
+    platform: z.string(),
+    terminal: z.string(),
+    gitRepo: z.boolean(),
+    version: z.string(),
+    messageCount: INTEGER.nonnegative(),
+    latestAssistantMessageId: z.string().nullable(),
+    transcript: z.array(z.unknown()),
+    errors: z.array(FeedbackError).nullable(),
+    subagentTranscripts: z.record(z.string(), z.unknown()).nullable(),
+    hasRawTranscript: z.boolean(),
+    createdAt: INTEGER.nonnegative(),
+});
+/** `GET` 的回体(管理员浏览队列)。 */
+export const FeedbackListResponse = z.object({ feedback: z.array(FeedbackWire) });

package/dist/api/pull-token.d.ts

@@ -0,0 +1,32 @@
+/** 一个令牌族:v1 / v2 两个前缀 + MAC 消息的标签。族是数据,铸法与验法只有一份。 */
+export interface ScopedTokenFamily {
+    readonly v1Prefix: string;
+    readonly v2Prefix: string;
+    readonly macTag: string;
+}
+/** worker 拉取令牌族(`WEB_ADMIN_ENV.token` 的值)。 */
+export declare const WORKER_PULL_TOKEN: {
+    readonly v1Prefix: "wpt_";
+    readonly v2Prefix: "wpt2_";
+    readonly macTag: "worker-pull";
+};
+/** 一枚令牌绑定的(worker, scope)。 */
+export interface ScopedTokenBinding {
+    worker: string;
+    scope: string;
+}
+/**
+ * 铸一枚按 scope 绑定的令牌(见模块头的两种形)。铸不出 ⇒ **抛**:共享密钥为空、scope 不是 scope id、worker 名为空或带 `_`。
+ * `scope` 缺省 = {@link GLOBAL_SCOPE}(v1)。
+ */
+export declare function mintScopedToken(family: ScopedTokenFamily, worker: string, shared: string, scope?: string): string;
+/**
+ * 读一枚令牌**声称**的绑定 —— 不验真(验真用 {@link verifyScopedToken})。v1 ⇒ 缺省 scope;v2 ⇒ 帧里的 scope;不是这一族的前缀、
+ * 帧切不开(缺 worker / 缺 mac / v2 缺 scope)⇒ `undefined`。
+ */
+export declare function readScopedTokenBinding(family: ScopedTokenFamily, presented: string): ScopedTokenBinding | undefined;
+/**
+ * 验一枚令牌:认领 → 按认领重铸正本 → 常量时间比对。是正本 ⇒ 它绑定的(worker, scope);否则(认领不出、认领的 scope 不是
+ * scope id、共享密钥为空、MAC 不对、v2 冒充缺省 scope)⇒ `undefined`。从不抛。
+ */
+export declare function verifyScopedToken(family: ScopedTokenFamily, presented: string, shared: string): ScopedTokenBinding | undefined;

package/dist/api/pull-token.js

@@ -0,0 +1,88 @@
+/**
+ * `api/pull-token` —— 按 scope 绑定的**令牌形与铸法**:web-admin 给每台 worker 铸一枚只够读它自己那份配置的拉取令牌
+ * (`WEB_ADMIN_ENV.token` 的值),收到时按同一条规则验。一条规则,**令牌族是数据**(前缀对 + MAC 标签):
+ *
+ *  · 缺省 scope(`GLOBAL_SCOPE`)⇒ v1:`<v1Prefix><worker>_<mac>`,`mac` = HMAC-SHA256(共享密钥, `<macTag>:v1:<worker>`) 的小写 hex;
+ *  · 其余 scope ⇒ v2:`<v2Prefix><scope>_<worker>_<mac>`,`mac` = HMAC-SHA256(共享密钥, `<macTag>:v2:<scope>:<worker>`)
+ *    —— MAC 消息里带着 scope,别的 scope 里同名的 worker 拿不出它。
+ *
+ * 帧按 `_` 切:scope id 是 slug(`SCOPE_ID_REGEX`,无 `_`),worker 名同样不许带 `_` —— 铸不出一枚切得开的令牌就**抛**,
+ * 不铸一枚永远验不过的令牌。共享密钥为空同样抛(不拿空钥签)。hex + 前缀 ⇒ 令牌里没有 `,` / `=`(可以原样放进
+ * `SERVICE_AUTH_TOKENS` 一类的 CSV)。
+ *
+ * 验 = 认领(从帧里读出它**声称**的 worker / scope,不信它)→ 按认领重铸正本 → 常量时间比对。一枚 v2 令牌声称缺省 scope 永远
+ * 验不过(缺省 scope 的正本是 v1)。
+ *
+ * 引擎只把这枚令牌当不透明 bearer 带着(它不铸、不验);铸与验都在 web-admin。纯函数,零 IO,browser-safe(HMAC 是本包自带的
+ * 纯 JS 实现,与 `node:crypto` 逐字节同)。
+ */
+import { hmacSha256Hex } from "../sha256-core.js";
+import { GLOBAL_SCOPE, SCOPE_ID_REGEX } from "./scopes.js";
+/** worker 拉取令牌族(`WEB_ADMIN_ENV.token` 的值)。 */
+export const WORKER_PULL_TOKEN = { v1Prefix: "wpt_", v2Prefix: "wpt2_", macTag: "worker-pull" };
+/** worker 名能不能进帧:非空、不带 `_`(帧的分隔符)。 */
+const framableWorker = (worker) => worker.length > 0 && !worker.includes("_");
+/**
+ * 铸一枚按 scope 绑定的令牌(见模块头的两种形)。铸不出 ⇒ **抛**:共享密钥为空、scope 不是 scope id、worker 名为空或带 `_`。
+ * `scope` 缺省 = {@link GLOBAL_SCOPE}(v1)。
+ */
+export function mintScopedToken(family, worker, shared, scope = GLOBAL_SCOPE) {
+    if (shared.length === 0)
+        throw new Error(`cannot mint a ${family.macTag} token: the shared key is empty`);
+    if (!framableWorker(worker))
+        throw new Error(`cannot mint a ${family.macTag} token: worker ${JSON.stringify(worker)} is empty or contains "_" (the frame separator)`);
+    if (scope === GLOBAL_SCOPE)
+        return `${family.v1Prefix}${worker}_${hmacSha256Hex(shared, `${family.macTag}:v1:${worker}`)}`;
+    if (!SCOPE_ID_REGEX.test(scope))
+        throw new Error(`cannot mint a ${family.macTag} token: scope ${JSON.stringify(scope)} is not a scope id`);
+    return `${family.v2Prefix}${scope}_${worker}_${hmacSha256Hex(shared, `${family.macTag}:v2:${scope}:${worker}`)}`;
+}
+/**
+ * 读一枚令牌**声称**的绑定 —— 不验真(验真用 {@link verifyScopedToken})。v1 ⇒ 缺省 scope;v2 ⇒ 帧里的 scope;不是这一族的前缀、
+ * 帧切不开(缺 worker / 缺 mac / v2 缺 scope)⇒ `undefined`。
+ */
+export function readScopedTokenBinding(family, presented) {
+    // v2 先判:族的 v2 前缀可能以 v1 前缀开头(`wpt2_` 不以 `wpt_` 开头,但规则不该依赖具体拼法)。
+    if (presented.startsWith(family.v2Prefix)) {
+        const rest = presented.slice(family.v2Prefix.length);
+        const first = rest.indexOf("_");
+        const last = rest.lastIndexOf("_");
+        if (first <= 0 || last <= first + 1 || last === rest.length - 1)
+            return undefined;
+        return { scope: rest.slice(0, first), worker: rest.slice(first + 1, last) };
+    }
+    if (presented.startsWith(family.v1Prefix)) {
+        const rest = presented.slice(family.v1Prefix.length);
+        const sep = rest.lastIndexOf("_");
+        if (sep <= 0 || sep === rest.length - 1)
+            return undefined;
+        return { worker: rest.slice(0, sep), scope: GLOBAL_SCOPE };
+    }
+    return undefined;
+}
+/** 常量时间比对(长度先比 —— 正本的长度不是秘密:前缀 + 名 + 64 位 hex)。 */
+function constantTimeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+/**
+ * 验一枚令牌:认领 → 按认领重铸正本 → 常量时间比对。是正本 ⇒ 它绑定的(worker, scope);否则(认领不出、认领的 scope 不是
+ * scope id、共享密钥为空、MAC 不对、v2 冒充缺省 scope)⇒ `undefined`。从不抛。
+ */
+export function verifyScopedToken(family, presented, shared) {
+    const claimed = readScopedTokenBinding(family, presented);
+    if (claimed === undefined)
+        return undefined;
+    let canonical;
+    try {
+        canonical = mintScopedToken(family, claimed.worker, shared, claimed.scope);
+    }
+    catch {
+        return undefined;
+    }
+    return constantTimeEqual(presented, canonical) ? claimed : undefined;
+}

package/dist/api/scopes.d.ts

@@ -1,9 +1,9 @@
 /**
- * `api/scopes` — the MULTI-TENANT SCOPE wire contract for the registry (/api/v1/scopes* +
- * /api/v1/auth/scope). Frozen here so sema-registry (the implementation), the orchestrator, workers and
+ * `api/scopes` — the MULTI-TENANT SCOPE wire contract for web-admin (/api/v1/scopes* +
+ * /api/v1/auth/scope). Frozen here so web-admin (the implementation), the orchestrator, workers and
  * the sema shell import ONE source of truth — same "契约先行" discipline as `api/auth`.
  *
- * THE SCOPE MODEL (normative — the registry implements EXACTLY this):
+ * THE SCOPE MODEL (normative — web-admin implements EXACTLY this):
  *
  *  - A **scope** is a tenant boundary: `{id, name, createdAt}`. `id` is a slug (SCOPE_ID_REGEX).
  *    The reserved id `"global"` (GLOBAL_SCOPE) is the DEFAULT scope: it always exists, is never
@@ -13,10 +13,10 @@
  *    and `viewer` in scope B.
  *  - The **instance-level** `users.role` is unchanged and orthogonal: an instance `admin` administers
  *    ALL scopes — inside any scope their effective role is always `"admin"` (see effectiveScopeRole).
- *  - The **access JWT** gains an OPTIONAL `scope` claim (SCOPE_CLAIM) binding the token to its active
- *    scope. A token WITHOUT the claim means `"global"` (tokenScopeOf) — full backward compatibility:
- *    every pre-scope token keeps working, scoped to global. The refresh token is NOT scope-bound;
- *    refresh re-mints per resolveTokenScope, and the client re-switches if it wants another scope.
+ *  - The **access JWT** carries a `scope` claim (SCOPE_CLAIM) binding the token to its active scope —
+ *    REQUIRED on read: a token without it is refused (readTokenScope ⇒ `scope_claim_missing`, answered 401);
+ *    it is not read as `"global"`. The refresh token is NOT scope-bound; refresh re-mints per
+ *    resolveTokenScope (always with the claim), and the client re-switches if it wants another scope.
  *
  * ENDPOINTS (paths in SCOPES_V1_PATHS / scopeMembersPath):
  *
@@ -37,10 +37,10 @@
  *
  * WIRE CASING: /api/v1/auth/scope is part of the OAuth face — snake_case on the wire (access_token,
  * expires_in), matching `api/auth`. The /api/v1/scopes management face uses this package's camelCase
- * (createdAt, scopeId) — it is a registry management API, not an OAuth endpoint.
+ * (createdAt, scopeId) — it is a web-admin management API, not an OAuth endpoint.
  *
  * Pure zod contract + pure decision functions — zero IO, browser-safe. The decision functions
- * (resolveTokenScope / canSwitchScope / effectiveScopeRole) are THE semantics: the registry
+ * (resolveTokenScope / canSwitchScope / effectiveScopeRole) are THE semantics: web-admin
  * implementation imports and calls these — it must not re-implement them.
  */
 import { z } from "zod";
@@ -51,14 +51,15 @@ export declare const GLOBAL_SCOPE = "global";
 export declare const RESERVED_SCOPE_IDS: readonly ["global"];
 /** Slug shape for scope ids: lowercase alphanumeric + inner dashes, 1–64 chars, no leading/trailing dash. */
 export declare const SCOPE_ID_REGEX: RegExp;
-/** The scope endpoints, relative to the registry origin. `members` needs the scope id — use scopeMembersPath. */
+/** The scope endpoints, relative to web-admin origin. `members` needs the scope id — use scopeMembersPath. */
 export declare const SCOPES_V1_PATHS: {
     /** GET (list) + POST (create). */
     readonly scopes: "/api/v1/scopes";
     /** POST — mint a new access token bound to another scope. */
     readonly authScope: "/api/v1/auth/scope";
 };
-/** The JWT claim carrying the token's active scope. OPTIONAL — absent means GLOBAL_SCOPE (tokenScopeOf). */
+/** The JWT claim carrying the token's active scope. Every minted access token carries it; a token without it is refused on read
+ *  ({@link readTokenScope}). */
 export declare const SCOPE_CLAIM = "scope";
 /** `/api/v1/scopes/{id}/members` for PUT (upsert) and DELETE (remove). */
 export declare function scopeMembersPath(scopeId: string): string;
@@ -69,230 +70,129 @@ export declare function isReservedScopeId(id: string): boolean;
 export declare const ScopeId: z.ZodString;
 export type ScopeId = z.infer<typeof ScopeId>;
 /** The per-scope role ladder = the existing instance RBAC ladder (viewer < editor < publisher < admin). */
-export declare const ScopeRole: z.ZodEnum<[UserRole, ...UserRole[]]>;
+export declare const ScopeRole: z.ZodEnum<{
+    viewer: "viewer";
+    editor: "editor";
+    publisher: "publisher";
+    admin: "admin";
+}>;
 export type ScopeRole = UserRole;
 /** The scope entity. */
 export declare const Scope: z.ZodObject<{
     id: z.ZodString;
-    /** Human display name (non-unique, non-secret). */
     name: z.ZodString;
-    /** Creation time, epoch MILLISECONDS. The reserved "global" scope reports its provisioning time. */
     createdAt: z.ZodNumber;
-}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-    id: z.ZodString;
-    /** Human display name (non-unique, non-secret). */
-    name: z.ZodString;
-    /** Creation time, epoch MILLISECONDS. The reserved "global" scope reports its provisioning time. */
-    createdAt: z.ZodNumber;
-}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-    id: z.ZodString;
-    /** Human display name (non-unique, non-secret). */
-    name: z.ZodString;
-    /** Creation time, epoch MILLISECONDS. The reserved "global" scope reports its provisioning time. */
-    createdAt: z.ZodNumber;
-}, z.ZodTypeAny, "passthrough">>;
+}, z.core.$loose>;
 export type Scope = z.infer<typeof Scope>;
 /** One membership row: `principal` holds `role` inside `scopeId`. Per-scope — the same principal may
  *  hold different roles in different scopes. */
 export declare const ScopeMember: z.ZodObject<{
     scopeId: z.ZodString;
-    /** The user identity — same principal string the JWT `sub` / x-agent-principal pipeline uses. */
-    principal: z.ZodString;
-    role: z.ZodEnum<[UserRole, ...UserRole[]]>;
-}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-    scopeId: z.ZodString;
-    /** The user identity — same principal string the JWT `sub` / x-agent-principal pipeline uses. */
     principal: z.ZodString;
-    role: z.ZodEnum<[UserRole, ...UserRole[]]>;
-}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-    scopeId: z.ZodString;
-    /** The user identity — same principal string the JWT `sub` / x-agent-principal pipeline uses. */
-    principal: z.ZodString;
-    role: z.ZodEnum<[UserRole, ...UserRole[]]>;
-}, z.ZodTypeAny, "passthrough">>;
+    role: z.ZodEnum<{
+        viewer: "viewer";
+        editor: "editor";
+        publisher: "publisher";
+        admin: "admin";
+    }>;
+}, z.core.$loose>;
 export type ScopeMember = z.infer<typeof ScopeMember>;
 /** One list entry: a scope the caller can act in, with the caller's EFFECTIVE role there
  *  (effectiveScopeRole — instance admins list every scope with role "admin"). */
 export declare const ScopeListEntry: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
-    role: z.ZodEnum<[UserRole, ...UserRole[]]>;
-}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-    id: z.ZodString;
-    name: z.ZodString;
-    role: z.ZodEnum<[UserRole, ...UserRole[]]>;
-}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-    id: z.ZodString;
-    name: z.ZodString;
-    role: z.ZodEnum<[UserRole, ...UserRole[]]>;
-}, z.ZodTypeAny, "passthrough">>;
+    role: z.ZodEnum<{
+        viewer: "viewer";
+        editor: "editor";
+        publisher: "publisher";
+        admin: "admin";
+    }>;
+}, z.core.$loose>;
 export type ScopeListEntry = z.infer<typeof ScopeListEntry>;
 export declare const ScopesListResponse: z.ZodObject<{
     scopes: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         name: z.ZodString;
-        role: z.ZodEnum<[UserRole, ...UserRole[]]>;
-    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-        id: z.ZodString;
-        name: z.ZodString;
-        role: z.ZodEnum<[UserRole, ...UserRole[]]>;
-    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-        id: z.ZodString;
-        name: z.ZodString;
-        role: z.ZodEnum<[UserRole, ...UserRole[]]>;
-    }, z.ZodTypeAny, "passthrough">>, "many">;
-}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-    scopes: z.ZodArray<z.ZodObject<{
-        id: z.ZodString;
-        name: z.ZodString;
-        role: z.ZodEnum<[UserRole, ...UserRole[]]>;
-    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-        id: z.ZodString;
-        name: z.ZodString;
-        role: z.ZodEnum<[UserRole, ...UserRole[]]>;
-    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-        id: z.ZodString;
-        name: z.ZodString;
-        role: z.ZodEnum<[UserRole, ...UserRole[]]>;
-    }, z.ZodTypeAny, "passthrough">>, "many">;
-}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-    scopes: z.ZodArray<z.ZodObject<{
-        id: z.ZodString;
-        name: z.ZodString;
-        role: z.ZodEnum<[UserRole, ...UserRole[]]>;
-    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-        id: z.ZodString;
-        name: z.ZodString;
-        role: z.ZodEnum<[UserRole, ...UserRole[]]>;
-    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-        id: z.ZodString;
-        name: z.ZodString;
-        role: z.ZodEnum<[UserRole, ...UserRole[]]>;
-    }, z.ZodTypeAny, "passthrough">>, "many">;
-}, z.ZodTypeAny, "passthrough">>;
+        role: z.ZodEnum<{
+            viewer: "viewer";
+            editor: "editor";
+            publisher: "publisher";
+            admin: "admin";
+        }>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
 export type ScopesListResponse = z.infer<typeof ScopesListResponse>;
 /** Request: the target scope. Errors: `invalid_request` (malformed), `access_denied` (not a member and
  *  not an instance admin — canSwitchScope false). */
 export declare const ScopeSwitchRequest: z.ZodObject<{
     scope: z.ZodString;
-}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-    scope: z.ZodString;
-}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-    scope: z.ZodString;
-}, z.ZodTypeAny, "passthrough">>;
+}, z.core.$loose>;
 export type ScopeSwitchRequest = z.infer<typeof ScopeSwitchRequest>;
 /** A fresh access token bound to the requested scope (`scope` claim = `scope` field below). The refresh
  *  grant is untouched — this endpoint never returns a refresh_token. `role` = the caller's effective role
  *  inside the new scope (effectiveScopeRole). */
 export declare const ScopeSwitchResponse: z.ZodObject<{
-    /** RS256 JWT with the `scope` claim set — verify per api/auth-bridge; VerifiedIdentity.scope carries it. */
-    access_token: z.ZodString;
-    token_type: z.ZodLiteral<"Bearer">;
-    /** Access-token lifetime in seconds (ACCESS_TOKEN_TTL_SECONDS — same mint as api/auth). */
-    expires_in: z.ZodNumber;
-    scope: z.ZodString;
-    role: z.ZodEnum<[UserRole, ...UserRole[]]>;
-}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-    /** RS256 JWT with the `scope` claim set — verify per api/auth-bridge; VerifiedIdentity.scope carries it. */
-    access_token: z.ZodString;
-    token_type: z.ZodLiteral<"Bearer">;
-    /** Access-token lifetime in seconds (ACCESS_TOKEN_TTL_SECONDS — same mint as api/auth). */
-    expires_in: z.ZodNumber;
-    scope: z.ZodString;
-    role: z.ZodEnum<[UserRole, ...UserRole[]]>;
-}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-    /** RS256 JWT with the `scope` claim set — verify per api/auth-bridge; VerifiedIdentity.scope carries it. */
     access_token: z.ZodString;
     token_type: z.ZodLiteral<"Bearer">;
-    /** Access-token lifetime in seconds (ACCESS_TOKEN_TTL_SECONDS — same mint as api/auth). */
     expires_in: z.ZodNumber;
     scope: z.ZodString;
-    role: z.ZodEnum<[UserRole, ...UserRole[]]>;
-}, z.ZodTypeAny, "passthrough">>;
+    role: z.ZodEnum<{
+        viewer: "viewer";
+        editor: "editor";
+        publisher: "publisher";
+        admin: "admin";
+    }>;
+}, z.core.$loose>;
 export type ScopeSwitchResponse = z.infer<typeof ScopeSwitchResponse>;
 /** Re-exported convenience: the switch endpoint mints through the SAME exit as api/auth (1h JWT). */
 export declare const SCOPE_SWITCH_TOKEN_TTL_SECONDS: number;
 /** Reserved ids ("global") are rejected AT THE SCHEMA — the default scope pre-exists and is not creatable. */
 export declare const ScopeCreateRequest: z.ZodObject<{
-    id: z.ZodEffects<z.ZodString, string, string>;
-    name: z.ZodString;
-}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-    id: z.ZodEffects<z.ZodString, string, string>;
-    name: z.ZodString;
-}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-    id: z.ZodEffects<z.ZodString, string, string>;
+    id: z.ZodString;
     name: z.ZodString;
-}, z.ZodTypeAny, "passthrough">>;
+}, z.core.$loose>;
 export type ScopeCreateRequest = z.infer<typeof ScopeCreateRequest>;
 /** The created scope, as stored. */
 export declare const ScopeCreateResponse: z.ZodObject<{
     id: z.ZodString;
-    /** Human display name (non-unique, non-secret). */
-    name: z.ZodString;
-    /** Creation time, epoch MILLISECONDS. The reserved "global" scope reports its provisioning time. */
-    createdAt: z.ZodNumber;
-}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-    id: z.ZodString;
-    /** Human display name (non-unique, non-secret). */
     name: z.ZodString;
-    /** Creation time, epoch MILLISECONDS. The reserved "global" scope reports its provisioning time. */
     createdAt: z.ZodNumber;
-}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-    id: z.ZodString;
-    /** Human display name (non-unique, non-secret). */
-    name: z.ZodString;
-    /** Creation time, epoch MILLISECONDS. The reserved "global" scope reports its provisioning time. */
-    createdAt: z.ZodNumber;
-}, z.ZodTypeAny, "passthrough">>;
+}, z.core.$loose>;
 export type ScopeCreateResponse = Scope;
 /** PUT body — upsert: sets `principal`'s role in the path scope, creating or replacing the row. */
 export declare const ScopeMemberUpsertRequest: z.ZodObject<{
     principal: z.ZodString;
-    role: z.ZodEnum<[UserRole, ...UserRole[]]>;
-}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-    principal: z.ZodString;
-    role: z.ZodEnum<[UserRole, ...UserRole[]]>;
-}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-    principal: z.ZodString;
-    role: z.ZodEnum<[UserRole, ...UserRole[]]>;
-}, z.ZodTypeAny, "passthrough">>;
+    role: z.ZodEnum<{
+        viewer: "viewer";
+        editor: "editor";
+        publisher: "publisher";
+        admin: "admin";
+    }>;
+}, z.core.$loose>;
 export type ScopeMemberUpsertRequest = z.infer<typeof ScopeMemberUpsertRequest>;
 /** The stored membership row (scopeId echoes the path). */
 export declare const ScopeMemberUpsertResponse: z.ZodObject<{
     scopeId: z.ZodString;
-    /** The user identity — same principal string the JWT `sub` / x-agent-principal pipeline uses. */
-    principal: z.ZodString;
-    role: z.ZodEnum<[UserRole, ...UserRole[]]>;
-}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-    scopeId: z.ZodString;
-    /** The user identity — same principal string the JWT `sub` / x-agent-principal pipeline uses. */
     principal: z.ZodString;
-    role: z.ZodEnum<[UserRole, ...UserRole[]]>;
-}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-    scopeId: z.ZodString;
-    /** The user identity — same principal string the JWT `sub` / x-agent-principal pipeline uses. */
-    principal: z.ZodString;
-    role: z.ZodEnum<[UserRole, ...UserRole[]]>;
-}, z.ZodTypeAny, "passthrough">>;
+    role: z.ZodEnum<{
+        viewer: "viewer";
+        editor: "editor";
+        publisher: "publisher";
+        admin: "admin";
+    }>;
+}, z.core.$loose>;
 export type ScopeMemberUpsertResponse = ScopeMember;
 /** DELETE body — remove `principal` from the path scope. */
 export declare const ScopeMemberDeleteRequest: z.ZodObject<{
     principal: z.ZodString;
-}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-    principal: z.ZodString;
-}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-    principal: z.ZodString;
-}, z.ZodTypeAny, "passthrough">>;
+}, z.core.$loose>;
 export type ScopeMemberDeleteRequest = z.infer<typeof ScopeMemberDeleteRequest>;
 /** Idempotent: `{ok:true}` whether or not the principal was a member (no membership disclosure beyond
  *  what the admin caller already sees). */
 export declare const ScopeMemberDeleteResponse: z.ZodObject<{
     ok: z.ZodLiteral<true>;
-}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-    ok: z.ZodLiteral<true>;
-}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-    ok: z.ZodLiteral<true>;
-}, z.ZodTypeAny, "passthrough">>;
+}, z.core.$loose>;
 export type ScopeMemberDeleteResponse = z.infer<typeof ScopeMemberDeleteResponse>;
 /** A membership as the decision functions see it (a projection of ScopeMember). */
 export interface ScopeMembershipInput {
@@ -317,7 +217,7 @@ export interface ResolvedTokenScope {
 export declare function effectiveScopeRole(membershipRole: UserRole | undefined, instanceRole: string): UserRole | undefined;
 /**
  * THE token-minting scope decision — which scope (and role claim) a fresh access token binds to, given
- * the principal's scope memberships and instance role. Deterministic; the registry (Node/Next) imports
+ * the principal's scope memberships and instance role. Deterministic; web-admin (Node/Next) imports
  * and calls this at every mint (device-flow grant AND refresh). NORMATIVE RULES (verbatim, 任务书拍定):
  *
  *   1. **唯一成员 scope** — exactly one membership → bind that scope, role = that membership's effective
@@ -342,11 +242,19 @@ export declare function resolveTokenScope(memberships: readonly ScopeMembershipI
  * membership cannot switch to global (their default mint never lands there either, rule 3 above).
  */
 export declare function canSwitchScope(memberships: readonly ScopeMembershipInput[], instanceRole: string, targetScope: string): boolean;
+/** Why {@link readTokenScope} refuses — a CLOSED set (one word today). */
+export declare const TOKEN_SCOPE_REFUSALS: readonly ["scope_claim_missing"];
+export type TokenScopeRefusal = (typeof TOKEN_SCOPE_REFUSALS)[number];
 /**
- * Read the active scope off verified JWT claims: a non-empty string `scope` claim, else GLOBAL_SCOPE.
- * This is the ONE place the "missing claim = global" backward-compat rule lives — workers and the
- * registry both call this instead of defaulting ad hoc.
+ * Read the active scope off verified JWT claims — the ONE reader. A non-empty string `scope` claim ⇒ `{ scope }`; a claim that is
+ * missing, empty or not a string ⇒ `{ refused: "scope_claim_missing" }` (the reader answers 401). There is no default scope here:
+ * every access token web-admin mints carries the claim, an access token lives at most {@link ACCESS_TOKEN_TTL_SECONDS}, and a refresh
+ * re-mints one with the claim — a token without it is not a token this contract reads (it used to be read as `"global"`).
  */
-export declare function tokenScopeOf(claims: {
+export declare function readTokenScope(claims: {
     scope?: unknown;
-}): string;
+}): {
+    scope: string;
+} | {
+    refused: TokenScopeRefusal;
+};