@sema-agent/settings-schema 10.1.1 → 11.1.0

package/dist/api/auth-bridge.js

@@ -1,11 +1,11 @@
 /**
  * `api/auth-bridge` — the 鉴权桥 contract: how a WORKER (the worker service / any data-plane service) verifies a
- * registry-minted USER access JWT and maps it into its existing `x-agent-principal` identity system.
- * (REGISTRY-REBUILD-DESIGN §5, M3 — registry half = JWKS already shipped; service half = ONE verifier
+ * web-admin-minted USER access JWT and maps it into its existing `x-agent-principal` identity system.
+ * (REGISTRY-REBUILD-DESIGN §5, M3 — web-admin half = JWKS already shipped; service half = ONE verifier
  * middleware implementing the rules below. This file is the schema + normative spec the service copies.)
  *
- * TRUST MODEL (single trust root, zero new worker config): the worker already trusts the registry for its
- * effective config; it extends the SAME trust to the registry's JWKS. A bearer token that is a well-formed
+ * TRUST MODEL (single trust root, zero new worker config): the worker already trusts web-admin for its
+ * effective config; it extends the SAME trust to web-admin's JWKS. A bearer token that is a well-formed
  * JWT and verifies against that JWKS with the checks below IS the user — `sub` feeds x-agent-principal
  * directly (owner semantics / costQuota / entitlement are already principal-keyed). Existing
  * SERVICE_AUTH_TOKENS / wpt_ bearer branches are untouched; this is an ADDITIONAL branch tried when the
@@ -19,25 +19,26 @@
  *     token whose header alg is absent. Pin the list in the JWT library call — never read alg from the
  *     token to decide how to verify.
  *
- *  R2 KEY SOURCE. Verification keys come from the registry JWKS endpoint `GET {registryBaseUrl}` +
- *     REGISTRY_JWKS_PATH ("/api/auth/sso/jwks"; response shape = `Jwks` below, public members only:
+ *  R2 KEY SOURCE. Verification keys come from the web-admin JWKS endpoint `GET {webAdminBaseUrl}` +
+ *     WEB_ADMIN_JWKS_PATH ("/api/auth/sso/jwks"; response shape = `Jwks` below, public members only:
  *     kty/n/e/kid/use/alg). Match the token header `kid` against cached keys.
  *
  *  R3 KID-MISS FORCED REFRESH + THROTTLE. kid found in cache → use the cached key (no fetch on the hot
  *     path). kid NOT in cache → force ONE JWKS refetch, then retry the match (this is the key-ROTATION
- *     window: a freshly rotated registry would otherwise reject every new token until the cache expired).
+ *     window: a freshly rotated web-admin would otherwise reject every new token until the cache expired).
  *     Forced refreshes are throttled to at most one per `jwksRefreshMinIntervalSec` (default 60s) —
  *     otherwise an attacker spraying random-kid tokens turns the verifier into a JWKS-fetch DoS cannon.
  *     Within the throttle window an unknown kid fails as `invalid_signature` WITHOUT fetching.
  *     (Decision function: `shouldForceJwksRefresh`.)
  *
- *  R4 ISSUER PIN. `iss` MUST equal the CONFIGURED issuer exactly (VerifierConfig.issuer = the registry's
+ *  R4 ISSUER PIN. `iss` MUST equal the CONFIGURED issuer exactly (VerifierConfig.issuer = web-admin's
  *     SSO_ISSUER, trailing slash stripped on both sides). A missing or different iss → `unknown_issuer`.
  *     Never derive the expected issuer from the token or from request headers.
  *
  *  R5 TIME WINDOW WITH SKEW. `exp` is REQUIRED: reject when nowSec > exp + clockSkewSec. `nbf`, when
- *     present: reject when nowSec < nbf - clockSkewSec. clockSkewSec default 60 (DEFAULT_CLOCK_SKEW_SEC).
- *     Both failures classify as `expired`. (Decision function: `classifyTimeClaims`.)
+ *     present: reject when nowSec < nbf - clockSkewSec. `iat`, when present: reject when nowSec < iat - clockSkewSec
+ *     (issued in the future). clockSkewSec default 60 (DEFAULT_CLOCK_SKEW_SEC), one tolerance for all three.
+ *     These failures classify as `expired`. (Decision function: `classifyTimeClaims`.)
  *
  *  R6 PRINCIPAL. `sub` MUST be a non-empty string — it becomes `VerifiedIdentity.principal` and feeds the
  *     existing x-agent-principal pipeline verbatim. Empty/missing sub → `malformed`.
@@ -48,14 +49,17 @@
  *
  *  R8 OFFLINE GRACE / FAIL-CLOSED. JWKS fetch fails (network/5xx/malformed body): keys already cached
  *     remain USABLE for up to `offlineGraceSec` (default 24h, DEFAULT_OFFLINE_GRACE_SEC) measured from the
- *     last SUCCESSFUL fetch — a registry blip must not take the whole data plane down. Past the grace, or
+ *     last SUCCESSFUL fetch — a web-admin blip must not take the whole data plane down. Past the grace, or
  *     with no cache at all, verification fails CLOSED as `jwks_unavailable` (never fail-open, never skip
  *     signature checks). (Decision function: `jwksWithinOfflineGrace`.)
  *
  *  R9 OUTPUT. Success → `VerifiedIdentity { principal: sub, role: token.role, grantId: token.jti,
- *     scope: token.scope }` (`scope` = the multi-tenant active scope claim, `api/scopes`; absent = "global").
- *     `role` is the registry RBAC role claim (string, informational for the worker's own authz mapping);
- *     `grantId` is the jti when the registry stamps one (absent today — optional forever). Failure → one
+ *     scope: token.scope, iat: token.iat }` (`scope` = the multi-tenant active scope claim, `api/scopes`; read it with
+ *     `readTokenScope` — an absent claim is refused, not read as "global"; `iat` = issued-at, integer seconds, carried
+ *     verbatim — a reader that learns a principal was deleted at T cuts off its tokens issued before T; absent claim ⇒ no
+ *     `iat` key; present but not a non-negative integer ⇒ the token is `malformed`).
+ *     `role` is web-admin RBAC role claim (string, informational for the worker's own authz mapping);
+ *     `grantId` is the jti when web-admin stamps one (absent today — optional forever). Failure → one
  *     of AUTH_BRIDGE_ERROR_CODES; the HTTP surface answers 401 with a GENERIC message (no error detail
  *     disclosure to the caller; the code goes to logs/metrics only).
  *
@@ -67,9 +71,10 @@
  * library; THESE shapes pin down its configuration), browser-safe.
  */
 import { z } from "zod";
+import { INTEGER } from "../integer.js";
 // ── constants ────────────────────────────────────────────────────────────────────────────────────────────
-/** The registry JWKS endpoint, relative to the registry origin (shipped; public by design, RFC 7517 §5). */
-export const REGISTRY_JWKS_PATH = "/api/auth/sso/jwks";
+/** The web-admin JWKS endpoint, relative to the web-admin origin (shipped; public by design, RFC 7517 §5). */
+export const WEB_ADMIN_JWKS_PATH = "/api/auth/sso/jwks";
 /** R1 — the ONLY acceptable JWS algorithms. */
 export const AUTH_BRIDGE_ALGS = ["RS256"];
 /** R5 — default tolerated clock skew (seconds) on exp/nbf. */
@@ -78,10 +83,15 @@ export const DEFAULT_CLOCK_SKEW_SEC = 60;
 export const DEFAULT_JWKS_REFRESH_MIN_INTERVAL_SEC = 60;
 /** R8 — default seconds a cached JWKS stays usable after fetches start failing (24h), then fail-closed. */
 export const DEFAULT_OFFLINE_GRACE_SEC = 24 * 60 * 60;
+/** R6 — the longest principal the data plane accepts: the engine's principal gate refuses a longer one (400), because every
+ *  scope / owner column a principal lands in verbatim is that wide — an over-long principal would truncate at the insert and
+ *  split one identity into two. Anyone validating or minting a principal (a token `sub`, a membership row, an outbound
+ *  principal header) checks against THIS value. */
+export const PRINCIPAL_MAX_LENGTH = 190;
 // ── JWKS wire shape (what GET /api/auth/sso/jwks returns) ────────────────────────────────────────────────
-/** One RSA public JWK as the registry publishes it (public members ONLY — a `d`/`p`/`q` here is a registry
+/** One RSA public JWK as web-admin publishes it (public members ONLY — a `d`/`p`/`q` here is a web-admin
  *  bug, but the verifier MUST still never use/echo private members). */
-export const RegistryJwk = z
+export const WebAdminJwk = z
     .object({
     kty: z.literal("RSA"),
     /** modulus, base64url */
@@ -94,27 +104,27 @@ export const RegistryJwk = z
     alg: z.enum(AUTH_BRIDGE_ALGS).optional(),
 })
     .passthrough();
-/** The JWKS document. `{keys: []}` is VALID (registry with SSO disabled) — every token then fails as
- *  `invalid_signature` (there is a registry, it just mints nothing). */
-export const RegistryJwks = z.object({ keys: z.array(RegistryJwk) }).passthrough();
+/** The JWKS document. `{keys: []}` is VALID (web-admin with SSO disabled) — every token then fails as
+ *  `invalid_signature` (there is a web-admin, it just mints nothing). */
+export const WebAdminJwks = z.object({ keys: z.array(WebAdminJwk) }).passthrough();
 // ── verifier configuration ───────────────────────────────────────────────────────────────────────────────
 /** Everything the service verifier is allowed to be configured with. In the zero-new-config deployment the
- *  worker derives `jwksUrl` from the registry base URL it already has (config pull) + REGISTRY_JWKS_PATH,
- *  and `issuer` from the same registry identity — but both stay explicit here so a split deployment
+ *  worker derives `jwksUrl` from web-admin base URL it already has (config pull) + WEB_ADMIN_JWKS_PATH,
+ *  and `issuer` from the same web-admin identity — but both stay explicit here so a split deployment
  *  (issuer behind a proxy ≠ fetch URL) is expressible. */
 export const VerifierConfig = z.object({
-    /** R4 — the EXACT expected `iss` (the registry's SSO_ISSUER). Compare with trailing slash stripped. */
+    /** R4 — the EXACT expected `iss` (web-admin's SSO_ISSUER). Compare with trailing slash stripped. */
     issuer: z.string().min(1),
-    /** R2 — absolute JWKS URL. Default: issuer (or the worker's registry base URL) + REGISTRY_JWKS_PATH. */
+    /** R2 — absolute JWKS URL. Default: issuer (or the worker's web-admin base URL) + WEB_ADMIN_JWKS_PATH. */
     jwksUrl: z.string().min(1).optional(),
     /** R7 — when set, `aud` must contain this value; unset = aud ignored. */
     audience: z.string().min(1).optional(),
     /** R5 — seconds of exp/nbf tolerance. Default DEFAULT_CLOCK_SKEW_SEC (60). */
-    clockSkewSec: z.number().int().nonnegative().default(DEFAULT_CLOCK_SKEW_SEC),
+    clockSkewSec: INTEGER.nonnegative().default(DEFAULT_CLOCK_SKEW_SEC),
     /** R3 — min seconds between forced kid-miss refetches. Default 60. */
-    jwksRefreshMinIntervalSec: z.number().int().nonnegative().default(DEFAULT_JWKS_REFRESH_MIN_INTERVAL_SEC),
+    jwksRefreshMinIntervalSec: INTEGER.nonnegative().default(DEFAULT_JWKS_REFRESH_MIN_INTERVAL_SEC),
     /** R8 — seconds a stale cache survives fetch failures before fail-closed. Default 86400 (24h). */
-    offlineGraceSec: z.number().int().nonnegative().default(DEFAULT_OFFLINE_GRACE_SEC),
+    offlineGraceSec: INTEGER.nonnegative().default(DEFAULT_OFFLINE_GRACE_SEC),
 });
 // ── verification outcome ─────────────────────────────────────────────────────────────────────────────────
 /** R9 failure classification — for logs/metrics/tests; the HTTP surface stays a generic 401. */
@@ -134,15 +144,21 @@ export const AUTH_BRIDGE_ERROR_CODES = [
 export const VerifiedIdentity = z.object({
     /** = token `sub`. Feeds x-agent-principal / owner semantics / costQuota / entitlement keying verbatim. */
     principal: z.string().min(1),
-    /** = token `role` claim (registry RBAC: admin/editor/viewer/…) — informational; the worker maps it to
+    /** = token `role` claim (web-admin RBAC: admin/editor/viewer/…) — informational; the worker maps it to
      *  its own authz, it does NOT replace worker-side entitlement checks. */
     role: z.string().optional(),
     /** = token `jti` when present (the auth_grants grant id — audit correlation). Absent today; optional forever. */
     grantId: z.string().optional(),
     /** = token `scope` claim when present (the active tenant scope, `api/scopes`) — transparently forwarded
-     *  to the worker's principal pipeline. ABSENT means the pre-scope/default token: semantically "global"
-     *  (use `tokenScopeOf` from api/scopes to normalize). Optional forever — backward compatible. */
+     *  to the worker's principal pipeline. Read it through `readTokenScope` (api/scopes): an ABSENT claim is refused
+     *  (`scope_claim_missing`), never read as "global". The field stays optional in this shape because the verifier
+     *  reports what the token carried; the scope decision is `readTokenScope`'s. */
     scope: z.string().optional(),
+    /** = token `iat` (issued-at, JWT NumericDate in SECONDS) when present, verbatim — a reader that learns a principal was
+     *  deleted at time T cuts off that principal's tokens issued before T. Absent claim ⇒ the key is absent (never minted);
+     *  a claim that is not a non-negative integer makes the token `malformed` (R9), and one issued later than now + the clock
+     *  skew is `expired` (R5, the same tolerance as `exp` / `nbf`). */
+    iat: INTEGER.nonnegative().optional(),
 });
 /**
  * R3 — should a token bearing `kid` trigger a forced JWKS refetch?
@@ -169,14 +185,17 @@ export function jwksWithinOfflineGrace(cache, cfg) {
 }
 /**
  * R5 — classify the token's time window. `exp` REQUIRED (a JWT without exp is not acceptable here —
- * registry tokens always carry one; classify a missing exp as "expired" so it can never live forever).
- * All values in SECONDS (JWT NumericDate).
+ * web-admin tokens always carry one; classify a missing exp as "expired" so it can never live forever).
+ * `nbf` / `iat`, when present, must not lie beyond now + skew (not yet valid / issued in the future).
+ * All values in SECONDS (JWT NumericDate); one tolerance (`clockSkewSec`) for all three.
  */
 export function classifyTimeClaims(claims, nowSec, clockSkewSec) {
     if (typeof claims.exp !== "number" || nowSec > claims.exp + clockSkewSec)
         return "expired";
     if (typeof claims.nbf === "number" && nowSec < claims.nbf - clockSkewSec)
         return "expired";
+    if (typeof claims.iat === "number" && nowSec < claims.iat - clockSkewSec)
+        return "expired";
     return "ok";
 }
 /**
@@ -186,6 +205,11 @@ export function classifyTimeClaims(claims, nowSec, clockSkewSec) {
 export function toVerifiedIdentity(payload, cfg) {
     if (typeof payload.sub !== "string" || payload.sub.length === 0)
         return { ok: false, error: "malformed" };
+    // The iat rule is the output field's own schema (one rule, not a second hand-written check).
+    const iatRead = VerifiedIdentity.shape.iat.safeParse(payload.iat);
+    if (!iatRead.success)
+        return { ok: false, error: "malformed" };
+    const iat = iatRead.data;
     if (cfg?.audience) {
         const aud = payload.aud;
         const match = typeof aud === "string" ? aud === cfg.audience : Array.isArray(aud) && aud.includes(cfg.audience);
@@ -199,6 +223,7 @@ export function toVerifiedIdentity(payload, cfg) {
             role: typeof payload.role === "string" && payload.role.length > 0 ? payload.role : undefined,
             grantId: typeof payload.jti === "string" && payload.jti.length > 0 ? payload.jti : undefined,
             scope: typeof payload.scope === "string" && payload.scope.length > 0 ? payload.scope : undefined,
+            ...(iat !== undefined ? { iat } : {}),
         },
     };
 }

package/dist/api/auth.d.ts

@@ -1,6 +1,6 @@
 /**
  * `api/auth` — the /api/v1/auth/* WIRE CONTRACT (REGISTRY-REBUILD-DESIGN §2.1/§2.2, M1 shipped in
- * sema-registry; this file freezes the shipped shapes so registry, orchestrator, service and the sema
+ * web-admin; this file freezes the shipped shapes so web-admin, orchestrator, service and the sema
  * shell import ONE source of truth — design §3 "契约先行").
  *
  * The flow is RFC 8628 (OAuth 2.0 Device Authorization Grant) + a rotating opaque refresh token:
@@ -19,35 +19,24 @@
  * WIRE CASING: these are OAuth-standard endpoints — fields are snake_case ON THE WIRE (access_token,
  * device_code, …), deliberately breaking this package's camelCase habit. Do not "fix" it.
  *
- * SECRET DISCIPLINE (registry side, informational for consumers): device_code and refresh_token are
+ * SECRET DISCIPLINE (web-admin side, informational for consumers): device_code and refresh_token are
  * ≥256-bit opaque strings persisted ONLY as SHA-256 hashes; access_token is the standard issueSsoToken
  * RS256 JWT (1h) — see `api/auth-bridge` for how a worker verifies it.
  *
  * Pure zod contract — zero IO, browser-safe, same rules as the rest of this package.
  *
- * ── 4.0.0:这一面**保留**(不删)。理由 / 谁该改调 / 什么条件下删 ───────────────────────────────
+ * ── 这一面**保留**(11.0.0 重核)。4.0.0 时写的「删的条件:零消费」已不成立 ─────────────────────────────
  *
- * 读数(4.0.0 前夜逐行核过,不是按计数下的结论):**没有任何消费仓 import 子路径 `./api/auth`**,
- * 也没有人从本包的桶里取这 18 个名(尺子:同一把 grep 在那几个仓里数 `@sema-agent/settings-schema`
- * 的 import 行,读数分别是几十到上百行 —— 所以那个零是真零,不是 grep 坏了)。**但零消费不等于这面死了**:
- * 上面第 2-4 行那句「大家 import ONE source of truth」今天是**意图**,不是读数 —— 真实情况是各抄了一份:
- *   · 管理面(配置控制台)`src/lib/auth/device-flow.ts` 自带一只 `normalizeUserCode`,函数体与本文件那只
- *     **逐字节相同**,另有自己的 `DEVICE_GRANT_TYPE` / `DEVICE_POLL_INTERVAL_SECONDS`;
- *   · 壳(命令行)`src/sema/cloudAuth.ts` 自声明 `DeviceCodeResponse` / `TokenResponse` 两只响应形;
- *   · SDK 在自己的 `registry/auth.ts` 里做**值拷贝**(`REGISTRY_AUTH_PATHS` / grant_type / 错误码集),
- *     并在**生产码**里把 `DeviceCodeResponse` / `TokenGrantResponse` 两只当类型 import —— 但取的是
- *     **改名前的那个旧包名**,靠它自己的「同源锚」测试对账;那道锚今天钉的是旧包(devDependency 停在
- *     0.17.1),于是本包改名之后的任何改动它都看不见。
- *     (所以上面那句「零 import」的**精确射程**是:没有任何仓从**本包这个名字**下取这 18 个名。)
- *
- * ⇒ 删掉这一面 = 把上面三份手抄就地合法化。凭据轴该有**单属主**,所以 4.0.0 取「迁移」不取「删」:
- *   · 谁该改调:管理面与壳直接 import 本面(先从 `normalizeUserCode` / 设备码响应形这几只开始);
- *     SDK 把它那道同源锚从旧包名改到本包(锚不动,漂移就永远是绿的)。
- *   · 什么条件下删:**下一个 major**,且届时三方都已改调(或各自明确表态不改并自己认账),且那时**仍**
- *     是零消费 —— 那天「删」的理由才成立。今天不成立:今天的零是手抄造出来的,不是这面没人要。
+ * 4.0.0 前夜这一面的读数是「没有任何仓从本包这个名字下取这几个名」,各方各抄一份;当时取「迁移」不取「删」,并写下删的前提
+ * = 届时仍零消费。迁移落了,前提就没了 —— 今天按子路径 `./api/auth` 引它的(`git grep`,含测试与文档行):
+ *   · web-admin:设备流、SSO、授权流的存储与激活页(生产码直接 import 本面);
+ *   · server:web-admin 凭证的续签器与对 web-admin 的请求(刷新令牌的路径与响应形);
+ *   · cli:壳的云登录与本机凭证文件(设备码 / 令牌响应形)。
+ * SDK 的值拷贝由它自己的构建期生成对表(不从本面 import,也不在本包这边计)。
+ * ⇒ 这一面是活的单源:不删、没有删的窗。加名 / 改形按发版纪律(新键 = 可选键;改名删名 = major + 三句)。
  */
 import { z } from "zod";
-/** The five auth endpoints, relative to the registry origin. */
+/** The five auth endpoints, relative to web-admin origin. */
 export declare const AUTH_V1_PATHS: {
     readonly deviceCode: "/api/v1/auth/device/code";
     readonly deviceToken: "/api/v1/auth/device/token";
@@ -91,191 +80,93 @@ export declare function nextPollInterval(currentIntervalSeconds: number, error:
 };
 /** The uniform error body. `error_description` is HUMAN diagnostic text — clients branch on `error` only. */
 export declare const OAuthErrorResponse: z.ZodObject<{
-    error: z.ZodEnum<["authorization_pending", "slow_down", "expired_token", "access_denied", "invalid_request", "unsupported_grant_type", "invalid_grant", "server_error"]>;
-    error_description: z.ZodOptional<z.ZodString>;
-}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-    error: z.ZodEnum<["authorization_pending", "slow_down", "expired_token", "access_denied", "invalid_request", "unsupported_grant_type", "invalid_grant", "server_error"]>;
-    error_description: z.ZodOptional<z.ZodString>;
-}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-    error: z.ZodEnum<["authorization_pending", "slow_down", "expired_token", "access_denied", "invalid_request", "unsupported_grant_type", "invalid_grant", "server_error"]>;
+    error: z.ZodEnum<{
+        invalid_request: "invalid_request";
+        server_error: "server_error";
+        authorization_pending: "authorization_pending";
+        slow_down: "slow_down";
+        expired_token: "expired_token";
+        access_denied: "access_denied";
+        unsupported_grant_type: "unsupported_grant_type";
+        invalid_grant: "invalid_grant";
+    }>;
     error_description: z.ZodOptional<z.ZodString>;
-}, z.ZodTypeAny, "passthrough">>;
+}, z.core.$loose>;
 export type OAuthErrorResponse = z.infer<typeof OAuthErrorResponse>;
 /** Unauthenticated by design (the client has no credentials yet). `client_name` is a NON-secret display
  *  hint for the consent screen ("sema CLI on macOS"); absent → the server falls back to the User-Agent.
  *  Body may be JSON or form-encoded; an empty body is legal. */
 export declare const DeviceCodeRequest: z.ZodObject<{
     client_name: z.ZodOptional<z.ZodString>;
-}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-    client_name: z.ZodOptional<z.ZodString>;
-}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-    client_name: z.ZodOptional<z.ZodString>;
-}, z.ZodTypeAny, "passthrough">>;
+}, z.core.$loose>;
 export type DeviceCodeRequest = z.infer<typeof DeviceCodeRequest>;
 /** RFC 8628 §3.2 device-authorization response. `device_code` is the client's polling secret (keep it in
  *  memory, never log it); `user_code` is the short human code ("XXXX-XXXX") the user approves. */
 export declare const DeviceCodeResponse: z.ZodObject<{
-    /** ≥256-bit opaque polling secret — returned ONCE, hash-persisted server-side. */
-    device_code: z.ZodString;
-    /** Human approval code, canonical shape "XXXX-XXXX" (base-20 alphabet: no vowels, no 0/O/1/I). */
-    user_code: z.ZodString;
-    /** The /activate page the user opens (any device, any logged-in browser). */
-    verification_uri: z.ZodString;
-    /** verification_uri with ?user_code= pre-filled — one-click / QR path. **OPTIONAL** (RFC 8628 §3.2):
-     *  absent ⇒ the reader shows `verification_uri` + `user_code`; present-but-empty is still refused. (5.0.0, S-615) */
-    verification_uri_complete: z.ZodOptional<z.ZodString>;
-    /** Seconds until the handshake expires (DEVICE_CODE_TTL_SECONDS). */
-    expires_in: z.ZodNumber;
-    /** Minimum seconds between polls (DEVICE_POLL_INTERVAL_SECONDS). */
-    interval: z.ZodNumber;
-}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-    /** ≥256-bit opaque polling secret — returned ONCE, hash-persisted server-side. */
-    device_code: z.ZodString;
-    /** Human approval code, canonical shape "XXXX-XXXX" (base-20 alphabet: no vowels, no 0/O/1/I). */
-    user_code: z.ZodString;
-    /** The /activate page the user opens (any device, any logged-in browser). */
-    verification_uri: z.ZodString;
-    /** verification_uri with ?user_code= pre-filled — one-click / QR path. **OPTIONAL** (RFC 8628 §3.2):
-     *  absent ⇒ the reader shows `verification_uri` + `user_code`; present-but-empty is still refused. (5.0.0, S-615) */
-    verification_uri_complete: z.ZodOptional<z.ZodString>;
-    /** Seconds until the handshake expires (DEVICE_CODE_TTL_SECONDS). */
-    expires_in: z.ZodNumber;
-    /** Minimum seconds between polls (DEVICE_POLL_INTERVAL_SECONDS). */
-    interval: z.ZodNumber;
-}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-    /** ≥256-bit opaque polling secret — returned ONCE, hash-persisted server-side. */
     device_code: z.ZodString;
-    /** Human approval code, canonical shape "XXXX-XXXX" (base-20 alphabet: no vowels, no 0/O/1/I). */
     user_code: z.ZodString;
-    /** The /activate page the user opens (any device, any logged-in browser). */
     verification_uri: z.ZodString;
-    /** verification_uri with ?user_code= pre-filled — one-click / QR path. **OPTIONAL** (RFC 8628 §3.2):
-     *  absent ⇒ the reader shows `verification_uri` + `user_code`; present-but-empty is still refused. (5.0.0, S-615) */
     verification_uri_complete: z.ZodOptional<z.ZodString>;
-    /** Seconds until the handshake expires (DEVICE_CODE_TTL_SECONDS). */
     expires_in: z.ZodNumber;
-    /** Minimum seconds between polls (DEVICE_POLL_INTERVAL_SECONDS). */
     interval: z.ZodNumber;
-}, z.ZodTypeAny, "passthrough">>;
+}, z.core.$loose>;
 export type DeviceCodeResponse = z.infer<typeof DeviceCodeResponse>;
 /** RFC 8628 §3.4 token request. Form or JSON. */
 export declare const DeviceTokenRequest: z.ZodObject<{
     grant_type: z.ZodLiteral<"urn:ietf:params:oauth:grant-type:device_code">;
     device_code: z.ZodString;
-}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-    grant_type: z.ZodLiteral<"urn:ietf:params:oauth:grant-type:device_code">;
-    device_code: z.ZodString;
-}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-    grant_type: z.ZodLiteral<"urn:ietf:params:oauth:grant-type:device_code">;
-    device_code: z.ZodString;
-}, z.ZodTypeAny, "passthrough">>;
+}, z.core.$loose>;
 export type DeviceTokenRequest = z.infer<typeof DeviceTokenRequest>;
 /** The ONE token success shape — shared by device/token AND token/refresh (both mint through the same
  *  exit: access = issueSsoToken RS256 JWT, refresh = fresh opaque rotating grant). */
 export declare const TokenGrantResponse: z.ZodObject<{
-    /** RS256 JWT — claims: sub (principal), iss, iat, exp, role; optional aud. Verify per api/auth-bridge. */
     access_token: z.ZodString;
-    /** NEW opaque rotating refresh token — replaces any previous one the client held. Store 0600/keychain. */
     refresh_token: z.ZodString;
     token_type: z.ZodLiteral<"Bearer">;
-    /** Access-token lifetime in seconds (ACCESS_TOKEN_TTL_SECONDS). */
     expires_in: z.ZodNumber;
-}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-    /** RS256 JWT — claims: sub (principal), iss, iat, exp, role; optional aud. Verify per api/auth-bridge. */
-    access_token: z.ZodString;
-    /** NEW opaque rotating refresh token — replaces any previous one the client held. Store 0600/keychain. */
-    refresh_token: z.ZodString;
-    token_type: z.ZodLiteral<"Bearer">;
-    /** Access-token lifetime in seconds (ACCESS_TOKEN_TTL_SECONDS). */
-    expires_in: z.ZodNumber;
-}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-    /** RS256 JWT — claims: sub (principal), iss, iat, exp, role; optional aud. Verify per api/auth-bridge. */
-    access_token: z.ZodString;
-    /** NEW opaque rotating refresh token — replaces any previous one the client held. Store 0600/keychain. */
-    refresh_token: z.ZodString;
-    token_type: z.ZodLiteral<"Bearer">;
-    /** Access-token lifetime in seconds (ACCESS_TOKEN_TTL_SECONDS). */
-    expires_in: z.ZodNumber;
-}, z.ZodTypeAny, "passthrough">>;
+}, z.core.$loose>;
 export type TokenGrantResponse = z.infer<typeof TokenGrantResponse>;
 /** Rotation is STRICT single-use: success revokes the presented grant and returns a NEW refresh_token;
  *  a replayed (or raced) old token answers `invalid_grant`. Clients MUST persist the new token before
  *  discarding the old request state. */
 export declare const TokenRefreshRequest: z.ZodObject<{
     refresh_token: z.ZodString;
-}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-    refresh_token: z.ZodString;
-}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-    refresh_token: z.ZodString;
-}, z.ZodTypeAny, "passthrough">>;
+}, z.core.$loose>;
 export type TokenRefreshRequest = z.infer<typeof TokenRefreshRequest>;
 /** Revoke the refresh grant. The already-minted access JWT stays valid until its 1h exp — revocation kills
  *  the RENEWAL path, which is the durable one. */
 export declare const LogoutRequest: z.ZodObject<{
     refresh_token: z.ZodString;
-}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-    refresh_token: z.ZodString;
-}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-    refresh_token: z.ZodString;
-}, z.ZodTypeAny, "passthrough">>;
+}, z.core.$loose>;
 export type LogoutRequest = z.infer<typeof LogoutRequest>;
 /** Always `{ok:true}` with HTTP 200 whether or not the token matched a live grant (RFC 7009: a revocation
  *  endpoint never discloses token existence). 400 only for a malformed request. */
 export declare const LogoutResponse: 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 LogoutResponse = z.infer<typeof LogoutResponse>;
 /** GET ?user_code=XXXX-XXXX — the consent screen's lookup, WITHOUT approving. 401 when not signed in;
  *  invalid_grant for an unknown/expired code. */
 export declare const DeviceApproveLookupResponse: z.ZodObject<{
     user_code: z.ZodString;
-    status: z.ZodEnum<["pending", "approved", "denied"]>;
-    /** The client_name/User-Agent display hint from device/code — null when the client sent none. */
+    status: z.ZodEnum<{
+        denied: "denied";
+        approved: "approved";
+        pending: "pending";
+    }>;
     client: z.ZodNullable<z.ZodString>;
-    /** Handshake expiry, epoch MILLISECONDS. */
     expires_at: z.ZodNumber;
-}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-    user_code: z.ZodString;
-    status: z.ZodEnum<["pending", "approved", "denied"]>;
-    /** The client_name/User-Agent display hint from device/code — null when the client sent none. */
-    client: z.ZodNullable<z.ZodString>;
-    /** Handshake expiry, epoch MILLISECONDS. */
-    expires_at: z.ZodNumber;
-}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-    user_code: z.ZodString;
-    status: z.ZodEnum<["pending", "approved", "denied"]>;
-    /** The client_name/User-Agent display hint from device/code — null when the client sent none. */
-    client: z.ZodNullable<z.ZodString>;
-    /** Handshake expiry, epoch MILLISECONDS. */
-    expires_at: z.ZodNumber;
-}, z.ZodTypeAny, "passthrough">>;
+}, z.core.$loose>;
 export type DeviceApproveLookupResponse = z.infer<typeof DeviceApproveLookupResponse>;
 /** POST body (JSON ONLY — the JSON content type is part of the cross-site-request defence; a cross-site
  *  form cannot send application/json without a CORS preflight). The approving identity comes from the
  *  session cookie exclusively — NEVER from this body. */
 export declare const DeviceApproveRequest: z.ZodObject<{
-    /** Case-insensitive; dashes/spaces optional — see normalizeUserCode. */
-    user_code: z.ZodString;
-}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-    /** Case-insensitive; dashes/spaces optional — see normalizeUserCode. */
     user_code: z.ZodString;
-}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-    /** Case-insensitive; dashes/spaces optional — see normalizeUserCode. */
-    user_code: z.ZodString;
-}, z.ZodTypeAny, "passthrough">>;
+}, z.core.$loose>;
 export type DeviceApproveRequest = z.infer<typeof DeviceApproveRequest>;
 export declare const DeviceApproveResponse: z.ZodObject<{
     ok: z.ZodLiteral<true>;
     user_code: z.ZodString;
-}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-    ok: z.ZodLiteral<true>;
-    user_code: z.ZodString;
-}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-    ok: z.ZodLiteral<true>;
-    user_code: z.ZodString;
-}, z.ZodTypeAny, "passthrough">>;
+}, z.core.$loose>;
 export type DeviceApproveResponse = z.infer<typeof DeviceApproveResponse>;

package/dist/api/auth.js

@@ -1,6 +1,6 @@
 /**
  * `api/auth` — the /api/v1/auth/* WIRE CONTRACT (REGISTRY-REBUILD-DESIGN §2.1/§2.2, M1 shipped in
- * sema-registry; this file freezes the shipped shapes so registry, orchestrator, service and the sema
+ * web-admin; this file freezes the shipped shapes so web-admin, orchestrator, service and the sema
  * shell import ONE source of truth — design §3 "契约先行").
  *
  * The flow is RFC 8628 (OAuth 2.0 Device Authorization Grant) + a rotating opaque refresh token:
@@ -19,38 +19,28 @@
  * WIRE CASING: these are OAuth-standard endpoints — fields are snake_case ON THE WIRE (access_token,
  * device_code, …), deliberately breaking this package's camelCase habit. Do not "fix" it.
  *
- * SECRET DISCIPLINE (registry side, informational for consumers): device_code and refresh_token are
+ * SECRET DISCIPLINE (web-admin side, informational for consumers): device_code and refresh_token are
  * ≥256-bit opaque strings persisted ONLY as SHA-256 hashes; access_token is the standard issueSsoToken
  * RS256 JWT (1h) — see `api/auth-bridge` for how a worker verifies it.
  *
  * Pure zod contract — zero IO, browser-safe, same rules as the rest of this package.
  *
- * ── 4.0.0:这一面**保留**(不删)。理由 / 谁该改调 / 什么条件下删 ───────────────────────────────
+ * ── 这一面**保留**(11.0.0 重核)。4.0.0 时写的「删的条件:零消费」已不成立 ─────────────────────────────
  *
- * 读数(4.0.0 前夜逐行核过,不是按计数下的结论):**没有任何消费仓 import 子路径 `./api/auth`**,
- * 也没有人从本包的桶里取这 18 个名(尺子:同一把 grep 在那几个仓里数 `@sema-agent/settings-schema`
- * 的 import 行,读数分别是几十到上百行 —— 所以那个零是真零,不是 grep 坏了)。**但零消费不等于这面死了**:
- * 上面第 2-4 行那句「大家 import ONE source of truth」今天是**意图**,不是读数 —— 真实情况是各抄了一份:
- *   · 管理面(配置控制台)`src/lib/auth/device-flow.ts` 自带一只 `normalizeUserCode`,函数体与本文件那只
- *     **逐字节相同**,另有自己的 `DEVICE_GRANT_TYPE` / `DEVICE_POLL_INTERVAL_SECONDS`;
- *   · 壳(命令行)`src/sema/cloudAuth.ts` 自声明 `DeviceCodeResponse` / `TokenResponse` 两只响应形;
- *   · SDK 在自己的 `registry/auth.ts` 里做**值拷贝**(`REGISTRY_AUTH_PATHS` / grant_type / 错误码集),
- *     并在**生产码**里把 `DeviceCodeResponse` / `TokenGrantResponse` 两只当类型 import —— 但取的是
- *     **改名前的那个旧包名**,靠它自己的「同源锚」测试对账;那道锚今天钉的是旧包(devDependency 停在
- *     0.17.1),于是本包改名之后的任何改动它都看不见。
- *     (所以上面那句「零 import」的**精确射程**是:没有任何仓从**本包这个名字**下取这 18 个名。)
- *
- * ⇒ 删掉这一面 = 把上面三份手抄就地合法化。凭据轴该有**单属主**,所以 4.0.0 取「迁移」不取「删」:
- *   · 谁该改调:管理面与壳直接 import 本面(先从 `normalizeUserCode` / 设备码响应形这几只开始);
- *     SDK 把它那道同源锚从旧包名改到本包(锚不动,漂移就永远是绿的)。
- *   · 什么条件下删:**下一个 major**,且届时三方都已改调(或各自明确表态不改并自己认账),且那时**仍**
- *     是零消费 —— 那天「删」的理由才成立。今天不成立:今天的零是手抄造出来的,不是这面没人要。
+ * 4.0.0 前夜这一面的读数是「没有任何仓从本包这个名字下取这几个名」,各方各抄一份;当时取「迁移」不取「删」,并写下删的前提
+ * = 届时仍零消费。迁移落了,前提就没了 —— 今天按子路径 `./api/auth` 引它的(`git grep`,含测试与文档行):
+ *   · web-admin:设备流、SSO、授权流的存储与激活页(生产码直接 import 本面);
+ *   · server:web-admin 凭证的续签器与对 web-admin 的请求(刷新令牌的路径与响应形);
+ *   · cli:壳的云登录与本机凭证文件(设备码 / 令牌响应形)。
+ * SDK 的值拷贝由它自己的构建期生成对表(不从本面 import,也不在本包这边计)。
+ * ⇒ 这一面是活的单源:不删、没有删的窗。加名 / 改形按发版纪律(新键 = 可选键;改名删名 = major + 三句)。
  */
 import { z } from "zod";
+import { INTEGER } from "../integer.js";
 // ── endpoint paths + protocol constants (shipped values) ─────────────────────────────────────────────────
 // 3.0.0(S-321):这些常量与纯函数 2026-07-27 曾被拆去 `./api/wire` 子路径(给「零依赖客户端运行时直取」
 // 留的门),四个消费仓自始至终零 import —— 死出口连同它的拆分一起删,常量回到它们的契约原处。
-/** The five auth endpoints, relative to the registry origin. */
+/** The five auth endpoints, relative to web-admin origin. */
 export const AUTH_V1_PATHS = {
     deviceCode: "/api/v1/auth/device/code",
     deviceToken: "/api/v1/auth/device/token",
@@ -85,7 +75,7 @@ export const OAUTH_ERROR_CODES = [
     "unsupported_grant_type",
     /** token/refresh + device/approve: unknown / expired / revoked / replayed token or code — no detail. */
     "invalid_grant",
-    /** SSO not configured on the registry (HTTP 503) — a deployment problem, not a client one. */
+    /** SSO not configured on web-admin (HTTP 503) — a deployment problem, not a client one. */
     "server_error",
 ];
 /** Handshake states a consent-screen lookup can see. (`approved` rows vanish once exchanged/consumed.)
@@ -150,9 +140,9 @@ export const DeviceCodeResponse = z
      *  absent ⇒ the reader shows `verification_uri` + `user_code`; present-but-empty is still refused. (5.0.0, S-615) */
     verification_uri_complete: z.string().min(1).optional(),
     /** Seconds until the handshake expires (DEVICE_CODE_TTL_SECONDS). */
-    expires_in: z.number().int().positive(),
+    expires_in: INTEGER.positive(),
     /** Minimum seconds between polls (DEVICE_POLL_INTERVAL_SECONDS). */
-    interval: z.number().int().positive(),
+    interval: INTEGER.positive(),
 })
     .passthrough();
 // ── POST /api/v1/auth/device/token (the poll) ────────────────────────────────────────────────────────────
@@ -173,7 +163,7 @@ export const TokenGrantResponse = z
     refresh_token: z.string().min(1),
     token_type: z.literal("Bearer"),
     /** Access-token lifetime in seconds (ACCESS_TOKEN_TTL_SECONDS). */
-    expires_in: z.number().int().positive(),
+    expires_in: INTEGER.positive(),
 })
     .passthrough();
 // ── POST /api/v1/auth/token/refresh ──────────────────────────────────────────────────────────────────────