@sema-agent/settings-schema 1.0.0

package/LICENSE

@@ -0,0 +1,103 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             clay (github.com/clayboby)
+Licensed Work:        @sema-agent/settings-schema (sema-registry-core)
+                      The Licensed Work is (c) 2026 clay.
+Additional Use Grant: You may make production use of the Licensed Work for
+                      personal, educational, research, or other
+                      non-commercial purposes. Commercial production use
+                      requires a commercial license from the Licensor.
+Change Date:          2030-07-13
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed
+Work, please contact the Licensor.
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+-----------------------------------------------------------------------------
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.
+
+-----------------------------------------------------------------------------
+
+Third-party notices
+
+Versions of this package up to and including 1.277.1 were published under the
+MIT License; those published copies remain governed by the license they were
+distributed under. This package incorporates design and (where noted) prompt
+content adapted from MIT-licensed projects — see NOTICE.md for attributions.

package/README.md

@@ -0,0 +1,129 @@
+# @sema-agent/settings-schema
+
+> **改名声明(1.0.0)**:本包自 **`1.0.0`** 起名为 `@sema-agent/settings-schema`;在此之前名为
+> **`@sema-agent/registry-core`(最后一版 `0.19.0`)**,更早还曾是 `@sema-ai/registry-core`。
+> **这是一次纯改名,不加料**:`0.19.0` → `1.0.0` 之间**零语义变更**——没有字段增删、没有校验收紧
+> (无 `.strict()` 化)、没有默认值改动、没有行为变化;`exports` 的 **21 个 subpath 一个不动**
+> (`.` / `./types` / `./node` / `./api/auth` / `./api/wire` …… 逐条 1:1 平移,只换包名前缀)。
+> 版号跳到 `1.0.0` **不是**「契约进入稳定期」的语义信号——改名需要一个不与旧 `0.x` 段混淆的新起点而已。
+>
+> **消费方迁移(两步,注意版号段也要动)**:
+> 1. `package.json` 依赖:`"@sema-agent/registry-core": "^0.19.0"` → `"@sema-agent/settings-schema": "^1.0.0"`。
+>    ⚠️ **只换名不换段会装不上** —— 新名的最低版本就是 `1.0.0`,`^0.19.0` 在新名下**没有任何匹配版本**,
+>    `npm install` 直接报 `No matching version found`。改完重生成 lockfile(`npm install` / `npm i --package-lock-only`)。
+> 2. 代码 import 说明符:`@sema-agent/registry-core…` → `@sema-agent/settings-schema…`(**纯前缀替换**,
+>    21 个 subpath 的后缀一个不动)。
+>
+> 这两步之外**什么都不用改**:没有 API 改名、没有类型改形、没有行为差异(实证见 CHANGELOG `1.0.0` 段的
+> 发布物 diff)。
+>
+> 旧名 `@sema-agent/registry-core`(≤`0.19.0`)保持已发布状态、**冻结不再出新版**,后续会打 npm
+> deprecate 标指向新名。
+
+Engine-agnostic, zero-dependency contract layer for the sema stack — **one source of truth** for the
+config domain across the center (the config-center product — today `sema-web` — the fleet admin), the
+server (the workers), and the client (desktop/CLI) seams. No two copies of the schema.
+
+> 命名说明:config-center 这个**产品**曾叫 `sema-registry`,现在是 `sema-web`(后续还会再改名)。
+> 本**包**名与产品名解耦,**不随产品改名而动**(1.0.0 这次改名是本包自身的正名,与产品名无关)——
+> 下文凡提「center / config-center 产品」即指该产品的当期实现。
+
+- **Source of truth**: `github.com/sema-agent/sema-registry-core`, branch `main` (private org repo).
+  仓名本步不动(只改包名)。
+- **npm**: published as `@sema-agent/settings-schema` on the public npm registry
+  (≤`0.19.0` 发在旧名 `@sema-agent/registry-core` 下,冻结)。
+
+The package is **pure**: zero `next`/`react`/server imports, zero DB drivers. Its only runtime dependency is
+`zod` (a `dependency` pinned `^3.24.0` — the same range the host repos (config-center 产品 / `sema-server` / CLI) use, so
+package managers dedup to a **single shared zod instance**, keeping cross-instance schema validation / `instanceof`
+sound). `npm ls --prod` therefore shows only `zod`. Node built-ins only (`node:crypto`, `node:fs`).
+
+## What's in it
+
+- **The zod contract** (`types.ts`): `DOMAIN_SCHEMAS` (17 domains — 0.10.0 adds `projects`, the project
+  identity ledger; 0.10.18 adds `prompts`; 0.19.0 adds `limits`, the cost/rate-limit publication slot),
+  `EffectiveConfig`, `EffectiveWire`,
+  `ENV_NAME`/`K8S_QUANTITY` boundaries, every domain's entry/config type.
+- **Pure config fns** (`config-fns.ts`): `buildEffective` (deterministic — `updatedAt` is a required param),
+  `parseDomain`, `emptyEffective` (epoch-seeded), `statusRowsToPrune`, role helpers (`roleAtLeast`,
+  `domainWriteRole`, …), `resolveActiveTiers`(0.9.0 档位组→引擎 `RunnerDeps.tiers`   组存 `models.tierGroups`+`models.activeTierGroup`,组切换=换表下发), and the pure data
+  shapes (`User`, `PublishedSnapshot`, …).
+- **Roster resolution** (`resolve-roster.ts`): `resolveEffectiveForWorker` → the per-worker wire payload.
+- **Ref integrity** (`cross-domain.ts`): `refIntegrityIssues` + `siblingResolver` (the pure half — fleet
+  auto-placement stays in the config-center 产品).
+- **Hashing** (`hash.ts`): `stableHash` (FNV-1a 64) for ETags / version detection.
+- **Skills manifest** (`skills-manifest.ts`): content-addressing for the lazy-pull skill bodies.
+- **Secret inventory** (`secret-refs.ts`): `collectEnvRefs` — every referenced env-NAME.
+- **The narrow reader** (`reader.ts`): `ConfigReader` (3 methods) — the config-center 产品's fat `ConfigStore`
+  `extends` it; a local file source / test fixture implements it without stubbing ~32 methods.
+- **`remoteExec` contract** (`remote-exec.ts`): the execution-substrate schema mirroring the service's
+  actual providers (`e2b` / `k8s` / `ssh` / `adb`), discriminated on `provider`; every secret an env-NAME ref.
+- **Auth wire contract** (`api/auth.ts`, subpath `./api/auth`): the `/api/v1/auth/*` face — RFC 8628
+  device flow (code / token poll / approve consent) + rotating refresh + logout, the OAuth error envelope,
+  and the pure client helpers `normalizeUserCode` / `nextPollInterval`. Shipped M1 shapes frozen.
+  OpenAPI mirror: `docs/openapi-auth.yaml` (auth face only).
+- **Auth bridge** (`api/auth-bridge.ts`, subpath `./api/auth-bridge`): the 鉴权桥 contract —
+  how a worker verifies a registry-minted user JWT: RS256-only, JWKS from `/api/auth/sso/jwks` with
+  kid-miss forced refresh + ≥60s throttle, exp/nbf clock skew (60s), 24h offline grace then fail-closed;
+  `VerifierConfig` / `VerifiedIdentity` / `AuthBridgeErrorCode` + pure decision fns
+  (`shouldForceJwksRefresh`, `jwksWithinOfflineGrace`, `classifyTimeClaims`, `toVerifiedIdentity`).
+  The normative rules R1–R10 in its header are the service verifier's implementation spec.
+  `VerifiedIdentity` carries an optional `scope` (the token's active tenant scope — see `api/scopes`).
+- **Multi-tenant scopes** (`api/scopes.ts`, subpath `./api/scopes`): the scope contract — the `Scope`
+  entity (`{id,name,createdAt}`, reserved default `"global"` always exists), per-scope `ScopeMember`
+  rows (`{scopeId,principal,role}` on the existing viewer<editor<publisher<admin ladder), the optional
+  JWT `scope` claim (absent = `"global"`, fully backward compatible; refresh tokens are never
+  scope-bound), and the wire shapes for `GET/POST /api/v1/scopes`, `POST /api/v1/auth/scope`
+  (scope-switch mint, OAuth-style errors) and `PUT/DELETE /api/v1/scopes/{id}/members`. The DECISION
+  SEMANTICS live here as pure functions the registry imports (never re-implements):
+  `resolveTokenScope` (mint-time scope binding: 1 membership → it; several incl. global → global;
+  several without global → lexicographically first; none → `{scope:"global", role:instanceRole}`),
+  `canSwitchScope` (member or instance admin), `effectiveScopeRole` (instance admin is `"admin"` in
+  every scope) and `tokenScopeOf` (missing claim = `"global"`). OpenAPI mirror: `docs/openapi-scopes.yaml`.
+- **Local file source** (`file-store.ts`, `file-edit.ts`): `FileConfigStore` reads `config.d/*.json` →
+  `EffectiveConfig`; `validateDomain` / `writeDomainFile` / `listRequiredEnvNames` are the TOC's
+  read/write/validate helpers. `getEffective({tolerant:true})` (0.10.12) isolates a malformed
+  catalog-domain file (that domain falls to its schema default, the error is listed in `domainErrors`)
+  instead of failing the whole read; gate domains (governance/rosters/entitlement/execution/runtime/
+  limits/workers) stay fail-loud even in tolerant mode. 0.19.0 adds a FAIL-LOUD sweep on the same read:
+  a `config.d/*.json` the local set will never read (a name that is not a domain, or a non-portable one)
+  and any top-level key a domain schema strips are both NAMED through `onWarning`
+  (`unread-config-file` / `unknown-keys-dropped`) instead of vanishing silently.
+
+## Secret boundary
+
+Every secret field is an **env-NAME**, never a value. The `ENV_NAME` regex (`/^[A-Z_][A-Z0-9_]*$/`) rejects a
+pasted credential. Values are resolved by the consumer from its own env (service env / k8s secret / the TOC
+local `.env`). This package never carries a credential.
+
+## Local file layout (TOC)
+
+```
+<root>/
+  config.d/
+    models.json rosters.json skills.json mcp.json scenarios.json plugins.json
+    collab.json runtime.json governance.json execution.json prompts.json limits.json
+    remote-exec.json      # NOT a domain (the exec backend; read by loadRemoteExec)
+  .env            # secret VALUES only (KEY=value); gitignored; never read into any *.json
+```
+
+Fleet-only domains (`workers`, `hosts`, `systems`) are omitted on a single machine — they resolve to schema
+defaults. Each `config.d/<domain>.json` is exactly that domain's zod object.
+
+## 发版纪律(semver)
+
+- **0.x 破坏性变更必 bump minor**(0.7 → 0.8),不许塞 patch——`^0.7.0` 这类脱字号 range 在 0.x 下
+  会自动收 patch,把 BREAKING 塞进 patch = 未 pin 精确版的下游 `npm install` 静默拿到破坏。
+- patch 只装:additive 字段、修 bug、文档/测试。commit message 的 `feat!`/`BREAKING` 标记照旧,
+  但标记不豁免版号义务。
+- **历史注记(0.7.1,2026-07-10)**:0.7.1 携带了两件预协调 BREAKING(撤 governance effective 双写
+  镜像、撤 QuotaLease 0.5 `tokens` 别名 shim)——名义上违反本条。当时下游(center/service 1.150.0)
+  均已显式迁移、实际破坏面为零,PM 拍板不重发 0.8.0(纯扰动);本段即为该例外的收账与今后的规矩。
+- 发布(单腿 npmjs,内网腿已废止):`npm run publish:npm`;发后必须 curl 直打 npmjs 复验 shasum。
+
+## 贡献指引
+
+- 真源 = `sema-agent/sema-registry-core` org 仓 `main`,所有变更直接落 org main(或 PR 进 main);
+  不再向任何个人位/镜像位 push。
+- 提交门 = `npm run build` + `npx vitest run`;改域/契约后必跑 `npm run e2e`(examples/toc-e2e.mjs)。
+- 契约破坏面动之前先盘 center / server / CLI 三方消费点;0.x 破坏性变更必 bump minor(见上节)。

package/dist/api/auth-bridge.d.ts

@@ -0,0 +1,331 @@
+/**
+ * `api/auth-bridge` — the 鉴权桥 contract: how a WORKER (sema-server / 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
+ * 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
+ * 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
+ * bearer LOOKS like a JWT (three dot-separated base64url segments).
+ *
+ * ════════════════════════════════════════════════════════════════════════════════════════════════════════
+ * NORMATIVE VERIFICATION RULES — the service verifier MUST implement ALL of these (copy as its spec):
+ *
+ *  R1 ALGORITHM WHITELIST. Accept `alg: RS256` ONLY (AUTH_BRIDGE_ALGS). Reject `none`, every HS* (an
+ *     HS-signed token verified against a PUBLIC key = classic alg-confusion forgery), the ES and PS families, and any
+ *     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:
+ *     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).
+ *     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
+ *     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`.)
+ *
+ *  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`.
+ *
+ *  R7 AUDIENCE (optional). When VerifierConfig.audience is set, `aud` must contain it (string equal or
+ *     array member); mismatch → `invalid_signature`-class rejection is WRONG — classify as `malformed`
+ *     (the token is valid but not FOR this worker). When audience is unset, `aud` is ignored.
+ *
+ *  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
+ *     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
+ *     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).
+ *
+ *  R10 NO CREDENTIAL LOGGING. Never log the token, any signature segment, or JWKS key material. Log
+ *      kid + error code + iss at most.
+ * ════════════════════════════════════════════════════════════════════════════════════════════════════════
+ *
+ * Pure zod contract + pure decision functions — zero IO, zero crypto here (the service brings its own JWT
+ * library; THESE shapes pin down its configuration), browser-safe.
+ */
+import { z } from "zod";
+/** The registry JWKS endpoint, relative to the registry origin (shipped; public by design, RFC 7517 §5). */
+export declare const REGISTRY_JWKS_PATH = "/api/auth/sso/jwks";
+/** R1 — the ONLY acceptable JWS algorithms. */
+export declare const AUTH_BRIDGE_ALGS: readonly ["RS256"];
+export type AuthBridgeAlg = (typeof AUTH_BRIDGE_ALGS)[number];
+/** R5 — default tolerated clock skew (seconds) on exp/nbf. */
+export declare const DEFAULT_CLOCK_SKEW_SEC = 60;
+/** R3 — default minimum seconds between FORCED (kid-miss) JWKS refetches. */
+export declare 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 declare const DEFAULT_OFFLINE_GRACE_SEC: number;
+/** One RSA public JWK as the registry publishes it (public members ONLY — a `d`/`p`/`q` here is a registry
+ *  bug, but the verifier MUST still never use/echo private members). */
+export declare const RegistryJwk: z.ZodObject<{
+    kty: z.ZodLiteral<"RSA">;
+    /** modulus, base64url */
+    n: z.ZodString;
+    /** exponent, base64url */
+    e: z.ZodString;
+    /** RFC 7638 thumbprint of the public JWK — the rotation-stable key id tokens carry in their header. */
+    kid: z.ZodString;
+    use: z.ZodOptional<z.ZodLiteral<"sig">>;
+    alg: z.ZodOptional<z.ZodEnum<["RS256"]>>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    kty: z.ZodLiteral<"RSA">;
+    /** modulus, base64url */
+    n: z.ZodString;
+    /** exponent, base64url */
+    e: z.ZodString;
+    /** RFC 7638 thumbprint of the public JWK — the rotation-stable key id tokens carry in their header. */
+    kid: z.ZodString;
+    use: z.ZodOptional<z.ZodLiteral<"sig">>;
+    alg: z.ZodOptional<z.ZodEnum<["RS256"]>>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    kty: z.ZodLiteral<"RSA">;
+    /** modulus, base64url */
+    n: z.ZodString;
+    /** exponent, base64url */
+    e: z.ZodString;
+    /** RFC 7638 thumbprint of the public JWK — the rotation-stable key id tokens carry in their header. */
+    kid: z.ZodString;
+    use: z.ZodOptional<z.ZodLiteral<"sig">>;
+    alg: z.ZodOptional<z.ZodEnum<["RS256"]>>;
+}, z.ZodTypeAny, "passthrough">>;
+export type RegistryJwk = z.infer<typeof RegistryJwk>;
+/** 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 declare const RegistryJwks: z.ZodObject<{
+    keys: z.ZodArray<z.ZodObject<{
+        kty: z.ZodLiteral<"RSA">;
+        /** modulus, base64url */
+        n: z.ZodString;
+        /** exponent, base64url */
+        e: z.ZodString;
+        /** RFC 7638 thumbprint of the public JWK — the rotation-stable key id tokens carry in their header. */
+        kid: z.ZodString;
+        use: z.ZodOptional<z.ZodLiteral<"sig">>;
+        alg: z.ZodOptional<z.ZodEnum<["RS256"]>>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        kty: z.ZodLiteral<"RSA">;
+        /** modulus, base64url */
+        n: z.ZodString;
+        /** exponent, base64url */
+        e: z.ZodString;
+        /** RFC 7638 thumbprint of the public JWK — the rotation-stable key id tokens carry in their header. */
+        kid: z.ZodString;
+        use: z.ZodOptional<z.ZodLiteral<"sig">>;
+        alg: z.ZodOptional<z.ZodEnum<["RS256"]>>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        kty: z.ZodLiteral<"RSA">;
+        /** modulus, base64url */
+        n: z.ZodString;
+        /** exponent, base64url */
+        e: z.ZodString;
+        /** RFC 7638 thumbprint of the public JWK — the rotation-stable key id tokens carry in their header. */
+        kid: z.ZodString;
+        use: z.ZodOptional<z.ZodLiteral<"sig">>;
+        alg: z.ZodOptional<z.ZodEnum<["RS256"]>>;
+    }, z.ZodTypeAny, "passthrough">>, "many">;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    keys: z.ZodArray<z.ZodObject<{
+        kty: z.ZodLiteral<"RSA">;
+        /** modulus, base64url */
+        n: z.ZodString;
+        /** exponent, base64url */
+        e: z.ZodString;
+        /** RFC 7638 thumbprint of the public JWK — the rotation-stable key id tokens carry in their header. */
+        kid: z.ZodString;
+        use: z.ZodOptional<z.ZodLiteral<"sig">>;
+        alg: z.ZodOptional<z.ZodEnum<["RS256"]>>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        kty: z.ZodLiteral<"RSA">;
+        /** modulus, base64url */
+        n: z.ZodString;
+        /** exponent, base64url */
+        e: z.ZodString;
+        /** RFC 7638 thumbprint of the public JWK — the rotation-stable key id tokens carry in their header. */
+        kid: z.ZodString;
+        use: z.ZodOptional<z.ZodLiteral<"sig">>;
+        alg: z.ZodOptional<z.ZodEnum<["RS256"]>>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        kty: z.ZodLiteral<"RSA">;
+        /** modulus, base64url */
+        n: z.ZodString;
+        /** exponent, base64url */
+        e: z.ZodString;
+        /** RFC 7638 thumbprint of the public JWK — the rotation-stable key id tokens carry in their header. */
+        kid: z.ZodString;
+        use: z.ZodOptional<z.ZodLiteral<"sig">>;
+        alg: z.ZodOptional<z.ZodEnum<["RS256"]>>;
+    }, z.ZodTypeAny, "passthrough">>, "many">;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    keys: z.ZodArray<z.ZodObject<{
+        kty: z.ZodLiteral<"RSA">;
+        /** modulus, base64url */
+        n: z.ZodString;
+        /** exponent, base64url */
+        e: z.ZodString;
+        /** RFC 7638 thumbprint of the public JWK — the rotation-stable key id tokens carry in their header. */
+        kid: z.ZodString;
+        use: z.ZodOptional<z.ZodLiteral<"sig">>;
+        alg: z.ZodOptional<z.ZodEnum<["RS256"]>>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        kty: z.ZodLiteral<"RSA">;
+        /** modulus, base64url */
+        n: z.ZodString;
+        /** exponent, base64url */
+        e: z.ZodString;
+        /** RFC 7638 thumbprint of the public JWK — the rotation-stable key id tokens carry in their header. */
+        kid: z.ZodString;
+        use: z.ZodOptional<z.ZodLiteral<"sig">>;
+        alg: z.ZodOptional<z.ZodEnum<["RS256"]>>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        kty: z.ZodLiteral<"RSA">;
+        /** modulus, base64url */
+        n: z.ZodString;
+        /** exponent, base64url */
+        e: z.ZodString;
+        /** RFC 7638 thumbprint of the public JWK — the rotation-stable key id tokens carry in their header. */
+        kid: z.ZodString;
+        use: z.ZodOptional<z.ZodLiteral<"sig">>;
+        alg: z.ZodOptional<z.ZodEnum<["RS256"]>>;
+    }, z.ZodTypeAny, "passthrough">>, "many">;
+}, z.ZodTypeAny, "passthrough">>;
+export type RegistryJwks = z.infer<typeof RegistryJwks>;
+/** 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
+ *  (issuer behind a proxy ≠ fetch URL) is expressible. */
+export declare const VerifierConfig: z.ZodObject<{
+    /** R4 — the EXACT expected `iss` (the registry's SSO_ISSUER). Compare with trailing slash stripped. */
+    issuer: z.ZodString;
+    /** R2 — absolute JWKS URL. Default: issuer (or the worker's registry base URL) + REGISTRY_JWKS_PATH. */
+    jwksUrl: z.ZodOptional<z.ZodString>;
+    /** R7 — when set, `aud` must contain this value; unset = aud ignored. */
+    audience: z.ZodOptional<z.ZodString>;
+    /** R5 — seconds of exp/nbf tolerance. Default DEFAULT_CLOCK_SKEW_SEC (60). */
+    clockSkewSec: z.ZodDefault<z.ZodNumber>;
+    /** R3 — min seconds between forced kid-miss refetches. Default 60. */
+    jwksRefreshMinIntervalSec: z.ZodDefault<z.ZodNumber>;
+    /** R8 — seconds a stale cache survives fetch failures before fail-closed. Default 86400 (24h). */
+    offlineGraceSec: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    issuer: string;
+    clockSkewSec: number;
+    jwksRefreshMinIntervalSec: number;
+    offlineGraceSec: number;
+    jwksUrl?: string | undefined;
+    audience?: string | undefined;
+}, {
+    issuer: string;
+    jwksUrl?: string | undefined;
+    audience?: string | undefined;
+    clockSkewSec?: number | undefined;
+    jwksRefreshMinIntervalSec?: number | undefined;
+    offlineGraceSec?: number | undefined;
+}>;
+export type VerifierConfig = z.infer<typeof VerifierConfig>;
+/** The pre-parse (all-optional-defaults) input shape, for consumers assembling config by hand. */
+export type VerifierConfigInput = z.input<typeof VerifierConfig>;
+/** R9 failure classification — for logs/metrics/tests; the HTTP surface stays a generic 401. */
+export declare const AUTH_BRIDGE_ERROR_CODES: readonly ["expired", "invalid_signature", "unknown_issuer", "jwks_unavailable", "malformed"];
+export type AuthBridgeErrorCode = (typeof AUTH_BRIDGE_ERROR_CODES)[number];
+/** R9 success output — what the verifier middleware hands the existing principal pipeline. */
+export declare const VerifiedIdentity: z.ZodObject<{
+    /** = token `sub`. Feeds x-agent-principal / owner semantics / costQuota / entitlement keying verbatim. */
+    principal: z.ZodString;
+    /** = token `role` claim (registry RBAC: admin/editor/viewer/…) — informational; the worker maps it to
+     *  its own authz, it does NOT replace worker-side entitlement checks. */
+    role: z.ZodOptional<z.ZodString>;
+    /** = token `jti` when present (the auth_grants grant id — audit correlation). Absent today; optional forever. */
+    grantId: z.ZodOptional<z.ZodString>;
+    /** = 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. */
+    scope: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    principal: string;
+    role?: string | undefined;
+    scope?: string | undefined;
+    grantId?: string | undefined;
+}, {
+    principal: string;
+    role?: string | undefined;
+    scope?: string | undefined;
+    grantId?: string | undefined;
+}>;
+export type VerifiedIdentity = z.infer<typeof VerifiedIdentity>;
+/** The verifier's total result — exactly one of ok/error. */
+export type AuthBridgeResult = {
+    ok: true;
+    identity: VerifiedIdentity;
+} | {
+    ok: false;
+    error: AuthBridgeErrorCode;
+};
+/** What the R3 cache logic needs to know — all times epoch ms supplied by the caller (pure, no clock). */
+export interface JwksCacheSnapshot {
+    /** kids currently in the cache (empty = never fetched / fetched empty). */
+    cachedKids: readonly string[];
+    /** epoch ms of the last fetch ATTEMPT (success or failure); undefined = never attempted. */
+    lastFetchAttemptMs?: number;
+    /** epoch ms of the last SUCCESSFUL fetch; undefined = never succeeded. */
+    lastFetchSuccessMs?: number;
+    nowMs: number;
+}
+/**
+ * R3 — should a token bearing `kid` trigger a forced JWKS refetch?
+ * true  ⇔ the kid is not cached AND we are outside the refresh throttle window.
+ * false ⇒ verify against the cache as-is (cached kid hit), or fail `invalid_signature` (unknown kid,
+ *         throttled) without fetching.
+ */
+export declare function shouldForceJwksRefresh(kid: string, cache: JwksCacheSnapshot, cfg: Pick<VerifierConfig, "jwksRefreshMinIntervalSec">): boolean;
+/**
+ * R8 — with the LATEST fetch having failed, may the cached keys still be used?
+ * true  ⇔ there WAS a successful fetch and it is at most offlineGraceSec old.
+ * false ⇒ fail closed: `jwks_unavailable`.
+ */
+export declare function jwksWithinOfflineGrace(cache: Pick<JwksCacheSnapshot, "lastFetchSuccessMs" | "nowMs">, cfg: Pick<VerifierConfig, "offlineGraceSec">): boolean;
+/**
+ * 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).
+ */
+export declare function classifyTimeClaims(claims: {
+    exp?: number;
+    nbf?: number;
+}, nowSec: number, clockSkewSec: number): "ok" | "expired";
+/**
+ * R6/R7/R9 — map a signature-verified payload to the identity, or reject. Pure: call AFTER the JWT
+ * library has verified signature (R1/R2/R3), issuer (R4) and time (R5).
+ */
+export declare function toVerifiedIdentity(payload: {
+    sub?: unknown;
+    role?: unknown;
+    jti?: unknown;
+    aud?: unknown;
+    scope?: unknown;
+}, cfg?: Pick<VerifierConfig, "audience">): AuthBridgeResult;
+/** Cheap pre-filter: does this bearer LOOK like a JWT (three non-empty dot-separated segments)? Use it to
+ *  route between the existing static-token branch and this verifier — NOT as any kind of validation. */
+export declare function looksLikeJwt(bearer: string): boolean;