@sema-agent/settings-schema 14.6.0 → 14.7.0

package/conformance/cases/c84-sandbox-git-block-carried-verbatim/expected.json

@@ -0,0 +1,153 @@
+{
+  "domains": {
+    "outcome": "effective",
+    "effective": {
+      "collab": {
+        "templates": []
+      },
+      "entitlement": {
+        "budgetGroups": [],
+        "groupBindings": [],
+        "subjects": [],
+        "tiers": []
+      },
+      "execution": {
+        "allowedLanes": [
+          "host"
+        ],
+        "required": false
+      },
+      "governance": {},
+      "hosts": {
+        "hosts": []
+      },
+      "limits": {},
+      "mcp": {
+        "servers": []
+      },
+      "models": {
+        "atMention": {
+          "mode": "all"
+        },
+        "models": [],
+        "roles": {},
+        "tierGroups": []
+      },
+      "plugins": {
+        "plugins": []
+      },
+      "projects": {
+        "projects": {}
+      },
+      "prompts": {},
+      "rosters": {
+        "rosters": []
+      },
+      "scenarios": {
+        "scenarios": []
+      },
+      "skills": {
+        "skills": []
+      },
+      "systems": {
+        "systems": []
+      },
+      "workers": {
+        "workers": []
+      }
+    },
+    "warnings": [],
+    "metadata": {
+      "version": 7,
+      "updatedAt": "2026-10-23T00:00:00.000Z"
+    }
+  },
+  "strictWrite": {
+    "outcome": "effective",
+    "effective": {},
+    "warnings": [],
+    "metadata": {
+      "version": 7,
+      "updatedAt": "2026-10-23T00:00:00.000Z"
+    },
+    "why": "受理空集:本条打的是 wire 腿(提交的域文档集为空)。"
+  },
+  "wire": {
+    "outcome": "effective",
+    "effective": {
+      "collab": {
+        "templates": []
+      },
+      "entitlement": {
+        "budgetGroups": [],
+        "groupBindings": [],
+        "subjects": [],
+        "tiers": []
+      },
+      "execution": {
+        "allowedLanes": [
+          "host"
+        ],
+        "required": false
+      },
+      "governance": {},
+      "hosts": {
+        "hosts": []
+      },
+      "limits": {},
+      "mcp": {
+        "servers": []
+      },
+      "models": {
+        "atMention": {
+          "mode": "all"
+        },
+        "models": [],
+        "roles": {},
+        "tierGroups": []
+      },
+      "plugins": {
+        "plugins": []
+      },
+      "projects": {
+        "projects": {}
+      },
+      "rosters": {
+        "rosters": []
+      },
+      "sandboxGit": {
+        "origins": [
+          {
+            "connectUrl": "https://console.example.com/connect/git",
+            "origin": "https://git.example.com:9999"
+          },
+          {
+            "connectUrl": "https://console.example.com/connect/git",
+            "origin": "http://git.legacy.example:8080"
+          }
+        ]
+      },
+      "scenarios": {
+        "scenarios": []
+      },
+      "skills": {
+        "skills": []
+      },
+      "systems": {
+        "systems": []
+      },
+      "workers": {
+        "workers": []
+      }
+    },
+    "warnings": [],
+    "metadata": {
+      "version": 7,
+      "updatedAt": "2026-10-23T00:00:00.000Z"
+    }
+  },
+  "localRoot": {
+    "derive": true,
+    "localVersion": 2617555914511015
+  }
+}

package/conformance/cases/c84-sandbox-git-block-carried-verbatim/input.json

@@ -0,0 +1,23 @@
+{
+  "meta": {
+    "version": 7,
+    "updatedAt": "2026-10-23T00:00:00.000Z"
+  },
+  "domains": {},
+  "wirePayload": {
+    "version": 7,
+    "updatedAt": "2026-10-23T00:00:00.000Z",
+    "sandboxGit": {
+      "origins": [
+        {
+          "origin": "https://git.example.com:9999",
+          "connectUrl": "https://console.example.com/connect/git"
+        },
+        {
+          "origin": "http://git.legacy.example:8080",
+          "connectUrl": "https://console.example.com/connect/git"
+        }
+      ]
+    }
+  }
+}

package/conformance/cases/c84-sandbox-git-block-carried-verbatim/meta.json

@@ -0,0 +1,5 @@
+{
+  "contributor": "contract",
+  "claim": "`sandboxGit` 是 /effective 载荷上的**非域**顶层键(web-admin 按部署登记册投影,不是存储域):wire 腿按 open-world 把它**逐字承运**(含块里的 http origin —— 它的拒因是逐 origin 应答里的一个词,不是块的校验拒),不出告警;其余三腿的入参里没有这个块,读出的 effective 里也不铸它(可选、无默认)。把它当域去校验、或当未知键丢掉的读腿,会让取值平面静默失去 origin 表。",
+  "firstRedOn": []
+}

package/conformance/cases/c85-sandbox-git-refused-block-still-carried/expected.json

@@ -0,0 +1,153 @@
+{
+  "domains": {
+    "outcome": "effective",
+    "effective": {
+      "collab": {
+        "templates": []
+      },
+      "entitlement": {
+        "budgetGroups": [],
+        "groupBindings": [],
+        "subjects": [],
+        "tiers": []
+      },
+      "execution": {
+        "allowedLanes": [
+          "host"
+        ],
+        "required": false
+      },
+      "governance": {},
+      "hosts": {
+        "hosts": []
+      },
+      "limits": {},
+      "mcp": {
+        "servers": []
+      },
+      "models": {
+        "atMention": {
+          "mode": "all"
+        },
+        "models": [],
+        "roles": {},
+        "tierGroups": []
+      },
+      "plugins": {
+        "plugins": []
+      },
+      "projects": {
+        "projects": {}
+      },
+      "prompts": {},
+      "rosters": {
+        "rosters": []
+      },
+      "scenarios": {
+        "scenarios": []
+      },
+      "skills": {
+        "skills": []
+      },
+      "systems": {
+        "systems": []
+      },
+      "workers": {
+        "workers": []
+      }
+    },
+    "warnings": [],
+    "metadata": {
+      "version": 7,
+      "updatedAt": "2026-10-23T00:00:00.000Z"
+    }
+  },
+  "strictWrite": {
+    "outcome": "effective",
+    "effective": {},
+    "warnings": [],
+    "metadata": {
+      "version": 7,
+      "updatedAt": "2026-10-23T00:00:00.000Z"
+    },
+    "why": "受理空集:本条打的是 wire 腿(提交的域文档集为空)。"
+  },
+  "wire": {
+    "outcome": "effective",
+    "effective": {
+      "collab": {
+        "templates": []
+      },
+      "entitlement": {
+        "budgetGroups": [],
+        "groupBindings": [],
+        "subjects": [],
+        "tiers": []
+      },
+      "execution": {
+        "allowedLanes": [
+          "host"
+        ],
+        "required": false
+      },
+      "governance": {},
+      "hosts": {
+        "hosts": []
+      },
+      "limits": {},
+      "mcp": {
+        "servers": []
+      },
+      "models": {
+        "atMention": {
+          "mode": "all"
+        },
+        "models": [],
+        "roles": {},
+        "tierGroups": []
+      },
+      "plugins": {
+        "plugins": []
+      },
+      "projects": {
+        "projects": {}
+      },
+      "rosters": {
+        "rosters": []
+      },
+      "sandboxGit": {
+        "origins": [
+          {
+            "connectUrl": "http://console.example.com/connect/git",
+            "origin": "https://Git.Example.com:443/"
+          },
+          {
+            "connectUrl": "https://console.example.com/connect/git",
+            "origin": "https://Git.Example.com:443/"
+          }
+        ]
+      },
+      "scenarios": {
+        "scenarios": []
+      },
+      "skills": {
+        "skills": []
+      },
+      "systems": {
+        "systems": []
+      },
+      "workers": {
+        "workers": []
+      }
+    },
+    "warnings": [],
+    "metadata": {
+      "version": 7,
+      "updatedAt": "2026-10-23T00:00:00.000Z"
+    }
+  },
+  "localRoot": {
+    "derive": true,
+    "localVersion": 2617555914511015
+  }
+}

package/conformance/cases/c85-sandbox-git-refused-block-still-carried/input.json

@@ -0,0 +1,23 @@
+{
+  "meta": {
+    "version": 7,
+    "updatedAt": "2026-10-23T00:00:00.000Z"
+  },
+  "domains": {},
+  "wirePayload": {
+    "version": 7,
+    "updatedAt": "2026-10-23T00:00:00.000Z",
+    "sandboxGit": {
+      "origins": [
+        {
+          "origin": "https://Git.Example.com:443/",
+          "connectUrl": "http://console.example.com/connect/git"
+        },
+        {
+          "origin": "https://Git.Example.com:443/",
+          "connectUrl": "https://console.example.com/connect/git"
+        }
+      ]
+    }
+  }
+}

package/conformance/cases/c85-sandbox-git-refused-block-still-carried/meta.json

@@ -0,0 +1,5 @@
+{
+  "contributor": "contract",
+  "claim": "块不合格(非规范形 origin、http 的 connectUrl、重复 origin)时 wire 腿**照样逐字承运**、不出告警:读腿不替消费方判 `sandboxGit`,判它的唯一座位是 `SandboxGitConfig`(消费方在用之前跑)。读腿若『好心』校验并丢弃坏块,消费方分不清『没有投影』与『投影坏了』。",
+  "firstRedOn": []
+}

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

@@ -54,10 +54,14 @@
  *     signature checks). (Decision function: `jwksWithinOfflineGrace`.)
  *
  *  R9 OUTPUT. Success → `VerifiedIdentity { principal: sub, role: token.role, grantId: token.jti,
- *     scope: token.scope, iat: token.iat }` (`scope` = the multi-tenant active scope claim, `api/scopes`; read it with
+ *     scope: token.scope, iat: token.iat, principalInc: token.sub_inc }` (`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`).
+ *     `iat` key; present but not a non-negative integer ⇒ the token is `malformed`; `principalInc` = the incarnation claim
+ *     {@link PRINCIPAL_INC_CLAIM} carried verbatim — the same name deleted and re-created is ANOTHER person, and this is what
+ *     tells the two apart; absent claim ⇒ no `principalInc` key — never a placeholder: what a reader does with a token that names
+ *     no incarnation is that reader's decision, not a refusal here; present but not a non-empty string ⇒ the token is `malformed`,
+ *     the same law as `sub`).
  *     `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
@@ -87,6 +91,14 @@ export declare const DEFAULT_OFFLINE_GRACE_SEC: number;
  *  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 declare const PRINCIPAL_MAX_LENGTH = 190;
+/** R9 — the token claim that carries the principal's INCARNATION: a deleted-and-re-created user keeps the name (`sub`) and gets a new
+ *  incarnation, so `sub` alone names a slot, not a person. One spelling for whoever mints the claim and whoever reads it
+ *  ({@link toVerifiedIdentity} reads it by this constant), the way `SCOPE_CLAIM` (`api/scopes`) is spelled once for the scope claim. */
+export declare const PRINCIPAL_INC_CLAIM = "sub_inc";
+/** One incarnation id: a non-empty string, opaque (never trimmed, folded or parsed). The token claim, {@link VerifiedIdentity.principalInc},
+ *  and every wire field that names an incarnation (the credential port's request and answer) are THIS schema — one rule, read by object. */
+export declare const PrincipalIncarnation: z.ZodString;
+export type PrincipalIncarnation = z.infer<typeof PrincipalIncarnation>;
 /** 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 declare const WebAdminJwk: z.ZodObject<{
@@ -140,6 +152,7 @@ export declare const VerifiedIdentity: z.ZodObject<{
     grantId: z.ZodOptional<z.ZodString>;
     scope: z.ZodOptional<z.ZodString>;
     iat: z.ZodOptional<z.ZodNumber>;
+    principalInc: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type VerifiedIdentity = z.infer<typeof VerifiedIdentity>;
 /** The verifier's total result — exactly one of ok/error. */
@@ -195,6 +208,7 @@ export declare function toVerifiedIdentity(payload: {
     aud?: unknown;
     scope?: unknown;
     iat?: unknown;
+    sub_inc?: 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. */

package/dist/api/auth-bridge.js

@@ -54,10 +54,14 @@
  *     signature checks). (Decision function: `jwksWithinOfflineGrace`.)
  *
  *  R9 OUTPUT. Success → `VerifiedIdentity { principal: sub, role: token.role, grantId: token.jti,
- *     scope: token.scope, iat: token.iat }` (`scope` = the multi-tenant active scope claim, `api/scopes`; read it with
+ *     scope: token.scope, iat: token.iat, principalInc: token.sub_inc }` (`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`).
+ *     `iat` key; present but not a non-negative integer ⇒ the token is `malformed`; `principalInc` = the incarnation claim
+ *     {@link PRINCIPAL_INC_CLAIM} carried verbatim — the same name deleted and re-created is ANOTHER person, and this is what
+ *     tells the two apart; absent claim ⇒ no `principalInc` key — never a placeholder: what a reader does with a token that names
+ *     no incarnation is that reader's decision, not a refusal here; present but not a non-empty string ⇒ the token is `malformed`,
+ *     the same law as `sub`).
  *     `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
@@ -72,6 +76,8 @@
  */
 import { z } from "zod";
 import { INTEGER } from "../integer.js";
+import { inspect, orWhenUninspectable, ownJsonOrThrow, ownOrThrow } from "../own-key-read.js";
+import { isJsonArray } from "../plain-json-object.js";
 // ── constants ────────────────────────────────────────────────────────────────────────────────────────────
 /** 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";
@@ -88,6 +94,13 @@ export const DEFAULT_OFFLINE_GRACE_SEC = 24 * 60 * 60;
  *  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;
+/** R9 — the token claim that carries the principal's INCARNATION: a deleted-and-re-created user keeps the name (`sub`) and gets a new
+ *  incarnation, so `sub` alone names a slot, not a person. One spelling for whoever mints the claim and whoever reads it
+ *  ({@link toVerifiedIdentity} reads it by this constant), the way `SCOPE_CLAIM` (`api/scopes`) is spelled once for the scope claim. */
+export const PRINCIPAL_INC_CLAIM = "sub_inc";
+/** One incarnation id: a non-empty string, opaque (never trimmed, folded or parsed). The token claim, {@link VerifiedIdentity.principalInc},
+ *  and every wire field that names an incarnation (the credential port's request and answer) are THIS schema — one rule, read by object. */
+export const PrincipalIncarnation = z.string().min(1);
 // ── JWKS wire shape (what GET /api/auth/sso/jwks returns) ────────────────────────────────────────────────
 /** 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). */
@@ -159,6 +172,11 @@ export const VerifiedIdentity = z.object({
      *  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(),
+    /** = token {@link PRINCIPAL_INC_CLAIM} (`sub_inc`) when present, verbatim — the principal's incarnation id ({@link PrincipalIncarnation}).
+     *  Absent claim ⇒ the key is absent (never minted; never `0`, `""` or any placeholder): a reader that needs an incarnation and finds none
+     *  answers "incarnation unrecorded" itself — that is not a refusal of the token. A claim that is not a non-empty string makes the token
+     *  `malformed` (R9): a broken issuer is not read as an old one. */
+    principalInc: PrincipalIncarnation.optional(),
 });
 /**
  * R3 — should a token bearing `kid` trigger a forced JWKS refetch?
@@ -203,29 +221,46 @@ export function classifyTimeClaims(claims, nowSec, clockSkewSec) {
  * library has verified signature (R1/R2/R3), issuer (R4) and time (R5).
  */
 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);
-        if (!match)
+    // Every claim is read from the payload's OWN keys (identity reads only what the token carries: a polluted `Object.prototype.role` is not a role the token was minted with,
+    // and a token with no `aud` is not given one); a claim that cannot be read ⇒ the token is malformed (fail-closed), never an engine error.
+    return orWhenUninspectable(() => {
+        const sub = ownOrThrow(payload, "sub"); // 只问「是不是非空串」:读一次值,不深拷
+        if (typeof sub !== "string" || sub.length === 0)
             return { ok: false, error: "malformed" };
-    }
-    return {
-        ok: true,
-        identity: {
-            principal: payload.sub,
-            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 } : {}),
-        },
-    };
+        // The iat and incarnation rules are the output fields' own schemas (one rule each, not a second hand-written check).
+        // Each schema call runs under `inspect`: the validator reads a snapshot THIS package took, and a throw there (a length check coercing an object value to a primitive) is not the caller's
+        // object being unreadable — but it is still no identity: the claim is malformed, and no engine error escapes the judge.
+        const iatRead = inspect(() => VerifiedIdentity.shape.iat.safeParse(ownJsonOrThrow(payload, "iat")));
+        if (!iatRead.ok || !iatRead.value.success)
+            return { ok: false, error: "malformed" };
+        const iat = iatRead.value.data;
+        const incRead = inspect(() => VerifiedIdentity.shape.principalInc.safeParse(ownJsonOrThrow(payload, PRINCIPAL_INC_CLAIM)));
+        if (!incRead.ok || !incRead.value.success)
+            return { ok: false, error: "malformed" };
+        const principalInc = incRead.value.data;
+        if (cfg?.audience) {
+            const aud = ownJsonOrThrow(payload, "aud");
+            const match = typeof aud === "string" ? aud === cfg.audience : isJsonArray(aud) && aud.includes(cfg.audience);
+            if (!match)
+                return { ok: false, error: "malformed" };
+        }
+        // role / jti / scope 只问「是不是非空串」(别的值读成缺省):读一次值,不深拷 —— 深拷会让「值是个带 Date 的对象」把整枚令牌拖成 malformed(v14.6.0 只做 typeof 判)。
+        // 要深拷的只有交给会反射它的代码的值:`aud`(数组上 `includes`)与 `iat` / `sub_inc`(交给校验器)
+        const role = ownOrThrow(payload, "role");
+        const jti = ownOrThrow(payload, "jti");
+        const scope = ownOrThrow(payload, "scope");
+        return {
+            ok: true,
+            identity: {
+                principal: sub,
+                role: typeof role === "string" && role.length > 0 ? role : undefined,
+                grantId: typeof jti === "string" && jti.length > 0 ? jti : undefined,
+                scope: typeof scope === "string" && scope.length > 0 ? scope : undefined,
+                ...(iat !== undefined ? { iat } : {}),
+                ...(principalInc !== undefined ? { principalInc } : {}),
+            },
+        };
+    }, () => ({ ok: false, error: "malformed" }));
 }
 /** 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. */