@sema-agent/settings-schema 14.6.0 → 14.8.0

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. */

package/dist/api/credentials.d.ts

@@ -0,0 +1,281 @@
+/**
+ * `api/credentials` —— 凭据取值口(`POST /api/v1/credentials/handles` → `POST /api/v1/credentials/resolve`)里 **`sandbox_git`** 这一种凭据的 wire 型(14.7.0)。
+ * 一份 zod,发这些形的一方(web-admin)与收这些形的一方(引擎的数据面)同 import。纯、浏览器安全。
+ *
+ * 两步:① 带调用方凭据申领一枚短期、一次性的**句柄**(请求 {@link SandboxGitCredentialRequest},应答 {@link CredentialHandleAnswer});
+ * ② 凭句柄兑换(请求 {@link CredentialResolveRequest},应答 {@link SandboxGitCredentialAnswer};不合格则整次拒答 {@link SandboxGitCredentialRefusal})。
+ * 本模块只有**形与词表**:调用方鉴权、委托、活表复核、行 MAC、租约算术、续期状态机、「应答与请求逐条对应 / 回显相等」的核对都是各方自己的事,不在这里。
+ * 取值口的另两种凭据(`model` / `mcp_static`)的请求与应答形不在本模块;它们落地时与本模块的 `sandbox_git` 形并成按 `kind` 判别的联合,
+ * 本模块的形不动(`kind` 字面量已经在)。
+ *
+ * ## 三张词表,各一张,每个词只在本文件里拼一次
+ *  · {@link SANDBOX_GIT_ORIGIN_VERDICTS} —— **逐 origin 判定序表**,11 行,序即判定序(首条命中即答;一个 origin 的结果不影响别的 origin)。
+ *    状态词({@link SANDBOX_GIT_ORIGIN_STATES},六个)与原因词({@link SANDBOX_GIT_ORIGIN_REASONS},十个)由它派生,没有第二张词表;`active` 行没有原因。
+ *    应答行({@link SandboxGitOriginAnswer})每个状态一个臂,臂里 `reason` 的值域 = 表里该状态的行 —— 状态与原因的配对由表定,臂不手写。
+ *    每一行的**条件**(什么事实使它命中)是 web-admin 的判定逻辑,写在 `docs/CONSUMER-INTEGRATION.md` 里,不进运行期表。
+ *  · {@link SANDBOX_GIT_REFUSALS} —— **整次拒答词**(十个)→ HTTP 状态集与 `permanence`;拒体里的 `permanence` 是错误词的函数,必须等于这一行的。
+ *  · {@link SANDBOX_GIT_PERMANENCE} —— `terminal`(不按定时重试)/ `transient`(退避重试)两词,语义在本表定义。
+ *
+ * ## 解析一律剥未知键
+ * 与包内 api 契约的前向兼容同律(新键恒为加性)。同时这也是一条安全律:`secret` 只在 `active` 臂的形里 —— 别的臂即使收到也剥掉,
+ * 解析出的值里不会带着谁多塞的秘密。`secret` 是应答里唯一的秘密位;`credentialId` / `version` / `auditId` 是不带值的审计位。
+ */
+import { z } from "zod";
+/**
+ * 逐 origin 判定序表(11 行,序即判定序)。每行 `{ state, reason? }`:命中这一行的 origin 的应答是这个状态与这个原因。
+ * 条件(各行什么事实命中)见 `docs/CONSUMER-INTEGRATION.md` 的判定序表;`active` 是兜底行(行 `active` 且刷新不成问题),没有原因。
+ * 加一行 / 改序都是改契约:状态词、原因词、应答臂的原因值域、类型全部随这一张表走。
+ */
+export declare const SANDBOX_GIT_ORIGIN_VERDICTS: readonly [{
+    readonly state: "insecure_transport";
+    readonly reason: "not_https";
+}, {
+    readonly state: "not_offered";
+    readonly reason: "not_in_registry";
+}, {
+    readonly state: "not_connected";
+    readonly reason: "no_row";
+}, {
+    readonly state: "not_connected";
+    readonly reason: "revoked";
+}, {
+    readonly state: "needs_reauth";
+    readonly reason: "revoking";
+}, {
+    readonly state: "needs_reauth";
+    readonly reason: "suspended";
+}, {
+    readonly state: "needs_reauth";
+    readonly reason: "row_needs_reauth";
+}, {
+    readonly state: "needs_reauth";
+    readonly reason: "integrity_failed";
+}, {
+    readonly state: "needs_reauth";
+    readonly reason: "refresh_rejected";
+}, {
+    readonly state: "temporarily_unavailable";
+    readonly reason: "refresh_unavailable";
+}, {
+    readonly state: "active";
+}];
+type Verdict = (typeof SANDBOX_GIT_ORIGIN_VERDICTS)[number];
+/** 逐 origin 状态词(闭集,六个)—— 类型由判定序表派生。 */
+export type SandboxGitOriginState = Verdict["state"];
+/** 逐 origin 原因词(闭集,十个)—— 类型由判定序表派生;`active` 行没有原因。 */
+export type SandboxGitOriginReason = Extract<Verdict, {
+    readonly reason: string;
+}>["reason"];
+/** 状态词表:判定序表里状态首次出现的次序。 */
+export declare const SANDBOX_GIT_ORIGIN_STATES: readonly [SandboxGitOriginState, ...SandboxGitOriginState[]];
+/** 原因词表:判定序表里原因出现的次序(= 判定序)。 */
+export declare const SANDBOX_GIT_ORIGIN_REASONS: readonly [SandboxGitOriginReason, ...SandboxGitOriginReason[]];
+/** 申领 `sandbox_git` 句柄的请求体。`origins` = 要取凭据的 origin(规范形、1–16 个、两两不同;http origin 也收 —— 中心对它答判定序第 1 行);`sid` = 会话 id(审计标签,不是安全边界)。 */
+export declare const SandboxGitCredentialRequest: z.ZodObject<{
+    origins: z.ZodArray<z.ZodString>;
+    sid: z.ZodString;
+    principal: z.ZodString;
+    principalInc: z.ZodString;
+    scope: z.ZodString;
+    kind: z.ZodLiteral<"sandbox_git">;
+}, z.core.$strip>;
+export type SandboxGitCredentialRequest = z.infer<typeof SandboxGitCredentialRequest>;
+/** 申领成功的应答:句柄(不透明串,一次性)与它的到期时刻(毫秒)。与凭据种类无关。 */
+export declare const CredentialHandleAnswer: z.ZodObject<{
+    handle: z.ZodString;
+    expiresAt: z.ZodNumber;
+}, z.core.$strip>;
+export type CredentialHandleAnswer = z.infer<typeof CredentialHandleAnswer>;
+/** 兑换请求:只有句柄 —— 调用方凭据在传输层,不在体里。与凭据种类无关。 */
+export declare const CredentialResolveRequest: z.ZodObject<{
+    handle: z.ZodString;
+}, z.core.$strip>;
+export type CredentialResolveRequest = z.infer<typeof CredentialResolveRequest>;
+/**
+ * 一个 origin 的应答行,按 `state` 判别。键集(判定序表之上的形):
+ *  · `active` 独有 `credentialId` `version` `username` `secret` `expiresAt`(OAuth 令牌:到期毫秒;个人访问令牌:`null`);没有 `reason`;
+ *  · `needs_reauth`(序 5–9)带 `credentialId`(不带值的审计位);
+ *  · 其余只有 `origin` / `state` / `reason`。
+ * 多给的键一律剥掉(见模块头注)。
+ */
+export declare const SandboxGitOriginAnswer: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    origin: z.ZodString;
+    state: z.ZodLiteral<"insecure_transport">;
+    reason: z.ZodEnum<{
+        not_https: "not_https";
+    }>;
+}, z.core.$strip>, z.ZodObject<{
+    origin: z.ZodString;
+    state: z.ZodLiteral<"not_offered">;
+    reason: z.ZodEnum<{
+        not_in_registry: "not_in_registry";
+    }>;
+}, z.core.$strip>, z.ZodObject<{
+    origin: z.ZodString;
+    state: z.ZodLiteral<"not_connected">;
+    reason: z.ZodEnum<{
+        no_row: "no_row";
+        revoked: "revoked";
+    }>;
+}, z.core.$strip>, z.ZodObject<{
+    origin: z.ZodString;
+    state: z.ZodLiteral<"needs_reauth">;
+    reason: z.ZodEnum<{
+        revoking: "revoking";
+        suspended: "suspended";
+        row_needs_reauth: "row_needs_reauth";
+        integrity_failed: "integrity_failed";
+        refresh_rejected: "refresh_rejected";
+    }>;
+    credentialId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    origin: z.ZodString;
+    state: z.ZodLiteral<"temporarily_unavailable">;
+    reason: z.ZodEnum<{
+        refresh_unavailable: "refresh_unavailable";
+    }>;
+}, z.core.$strip>, z.ZodObject<{
+    origin: z.ZodString;
+    state: z.ZodLiteral<"active">;
+    credentialId: z.ZodString;
+    version: z.ZodNumber;
+    username: z.ZodString;
+    secret: z.ZodString;
+    expiresAt: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>], "state">;
+export type SandboxGitOriginAnswer = z.infer<typeof SandboxGitOriginAnswer>;
+/**
+ * 取值应答(200)。`principal` / `principalInc` / `scope` 是请求的**回显**;`answeredAt`(应答时刻)、`cacheUntil`(句柄到期,收方不得把凭据缓存过它)与行里的 `expiresAt`
+ * 是**同一只钟**(中心的)给的毫秒 —— 收方只该用它们的**差**,不拿它们和自己的钟比。`auditId` = 审计行 id(不带值)。
+ * `origins` 与请求逐条对应(同序同长)是收方要核的事,本形只钉 1–{@link SANDBOX_GIT_MAX_ORIGINS} 条。
+ */
+export declare const SandboxGitCredentialAnswer: z.ZodObject<{
+    auditId: z.ZodString;
+    answeredAt: z.ZodNumber;
+    cacheUntil: z.ZodNumber;
+    origins: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        origin: z.ZodString;
+        state: z.ZodLiteral<"insecure_transport">;
+        reason: z.ZodEnum<{
+            not_https: "not_https";
+        }>;
+    }, z.core.$strip>, z.ZodObject<{
+        origin: z.ZodString;
+        state: z.ZodLiteral<"not_offered">;
+        reason: z.ZodEnum<{
+            not_in_registry: "not_in_registry";
+        }>;
+    }, z.core.$strip>, z.ZodObject<{
+        origin: z.ZodString;
+        state: z.ZodLiteral<"not_connected">;
+        reason: z.ZodEnum<{
+            no_row: "no_row";
+            revoked: "revoked";
+        }>;
+    }, z.core.$strip>, z.ZodObject<{
+        origin: z.ZodString;
+        state: z.ZodLiteral<"needs_reauth">;
+        reason: z.ZodEnum<{
+            revoking: "revoking";
+            suspended: "suspended";
+            row_needs_reauth: "row_needs_reauth";
+            integrity_failed: "integrity_failed";
+            refresh_rejected: "refresh_rejected";
+        }>;
+        credentialId: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        origin: z.ZodString;
+        state: z.ZodLiteral<"temporarily_unavailable">;
+        reason: z.ZodEnum<{
+            refresh_unavailable: "refresh_unavailable";
+        }>;
+    }, z.core.$strip>, z.ZodObject<{
+        origin: z.ZodString;
+        state: z.ZodLiteral<"active">;
+        credentialId: z.ZodString;
+        version: z.ZodNumber;
+        username: z.ZodString;
+        secret: z.ZodString;
+        expiresAt: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>], "state">>;
+    principal: z.ZodString;
+    principalInc: z.ZodString;
+    scope: z.ZodString;
+    kind: z.ZodLiteral<"sandbox_git">;
+}, z.core.$strip>;
+export type SandboxGitCredentialAnswer = z.infer<typeof SandboxGitCredentialAnswer>;
+/** `permanence` 两词:`terminal` = 不按定时重试;`transient` = 退避重试。 */
+export declare const SANDBOX_GIT_PERMANENCE: readonly ["terminal", "transient"];
+export type SandboxGitPermanence = (typeof SANDBOX_GIT_PERMANENCE)[number];
+/**
+ * 整次拒答词 → 它的 HTTP 状态集(中心答这个词时用其一)与 `permanence`。**一个错误词的 permanence 是固定的**,拒体里再带一份只为让收方不必查表 ——
+ * 两处不一致就是畸形应答({@link SandboxGitCredentialRefusal} 拒)。收方怎么处置某个词(例如哪些 terminal 可由用户动作恢复)是收方的状态机,不在这里。
+ */
+export declare const SANDBOX_GIT_REFUSALS: {
+    readonly caller_not_admitted: {
+        readonly statuses: readonly [401, 403];
+        readonly permanence: "terminal";
+    };
+    readonly scope_mismatch: {
+        readonly statuses: readonly [403];
+        readonly permanence: "terminal";
+    };
+    readonly incarnation_mismatch: {
+        readonly statuses: readonly [403];
+        readonly permanence: "terminal";
+    };
+    readonly request_invalid: {
+        readonly statuses: readonly [400];
+        readonly permanence: "terminal";
+    };
+    readonly principal_not_live: {
+        readonly statuses: readonly [403];
+        readonly permanence: "terminal";
+    };
+    readonly delegation_required: {
+        readonly statuses: readonly [403];
+        readonly permanence: "terminal";
+    };
+    readonly vault_disabled: {
+        readonly statuses: readonly [503];
+        readonly permanence: "terminal";
+    };
+    readonly vault_frozen: {
+        readonly statuses: readonly [503];
+        readonly permanence: "terminal";
+    };
+    readonly handle_invalid: {
+        readonly statuses: readonly [401];
+        readonly permanence: "transient";
+    };
+    readonly vault_unavailable: {
+        readonly statuses: readonly [503];
+        readonly permanence: "transient";
+    };
+};
+/** 整次拒答词(闭集,十个)—— 类型由 {@link SANDBOX_GIT_REFUSALS} 派生。 */
+export type SandboxGitRefusalError = keyof typeof SANDBOX_GIT_REFUSALS;
+/** 整次拒答词表(运行期;表的键,按表序)。 */
+export declare const SANDBOX_GIT_REFUSAL_ERRORS: readonly [SandboxGitRefusalError, ...SandboxGitRefusalError[]];
+/** 整次拒答的体:`{ error, permanence, message }`。`message` 是中心的诊断句(收方不据它判,可为空串)。 */
+export declare const SandboxGitCredentialRefusal: z.ZodObject<{
+    error: z.ZodEnum<{
+        caller_not_admitted: "caller_not_admitted";
+        scope_mismatch: "scope_mismatch";
+        incarnation_mismatch: "incarnation_mismatch";
+        request_invalid: "request_invalid";
+        principal_not_live: "principal_not_live";
+        delegation_required: "delegation_required";
+        vault_disabled: "vault_disabled";
+        vault_frozen: "vault_frozen";
+        handle_invalid: "handle_invalid";
+        vault_unavailable: "vault_unavailable";
+    }>;
+    permanence: z.ZodEnum<{
+        terminal: "terminal";
+        transient: "transient";
+    }>;
+    message: z.ZodString;
+}, z.core.$strip>;
+export type SandboxGitCredentialRefusal = z.infer<typeof SandboxGitCredentialRefusal>;
+export {};

package/dist/api/credentials.js

@@ -0,0 +1,149 @@
+/**
+ * `api/credentials` —— 凭据取值口(`POST /api/v1/credentials/handles` → `POST /api/v1/credentials/resolve`)里 **`sandbox_git`** 这一种凭据的 wire 型(14.7.0)。
+ * 一份 zod,发这些形的一方(web-admin)与收这些形的一方(引擎的数据面)同 import。纯、浏览器安全。
+ *
+ * 两步:① 带调用方凭据申领一枚短期、一次性的**句柄**(请求 {@link SandboxGitCredentialRequest},应答 {@link CredentialHandleAnswer});
+ * ② 凭句柄兑换(请求 {@link CredentialResolveRequest},应答 {@link SandboxGitCredentialAnswer};不合格则整次拒答 {@link SandboxGitCredentialRefusal})。
+ * 本模块只有**形与词表**:调用方鉴权、委托、活表复核、行 MAC、租约算术、续期状态机、「应答与请求逐条对应 / 回显相等」的核对都是各方自己的事,不在这里。
+ * 取值口的另两种凭据(`model` / `mcp_static`)的请求与应答形不在本模块;它们落地时与本模块的 `sandbox_git` 形并成按 `kind` 判别的联合,
+ * 本模块的形不动(`kind` 字面量已经在)。
+ *
+ * ## 三张词表,各一张,每个词只在本文件里拼一次
+ *  · {@link SANDBOX_GIT_ORIGIN_VERDICTS} —— **逐 origin 判定序表**,11 行,序即判定序(首条命中即答;一个 origin 的结果不影响别的 origin)。
+ *    状态词({@link SANDBOX_GIT_ORIGIN_STATES},六个)与原因词({@link SANDBOX_GIT_ORIGIN_REASONS},十个)由它派生,没有第二张词表;`active` 行没有原因。
+ *    应答行({@link SandboxGitOriginAnswer})每个状态一个臂,臂里 `reason` 的值域 = 表里该状态的行 —— 状态与原因的配对由表定,臂不手写。
+ *    每一行的**条件**(什么事实使它命中)是 web-admin 的判定逻辑,写在 `docs/CONSUMER-INTEGRATION.md` 里,不进运行期表。
+ *  · {@link SANDBOX_GIT_REFUSALS} —— **整次拒答词**(十个)→ HTTP 状态集与 `permanence`;拒体里的 `permanence` 是错误词的函数,必须等于这一行的。
+ *  · {@link SANDBOX_GIT_PERMANENCE} —— `terminal`(不按定时重试)/ `transient`(退避重试)两词,语义在本表定义。
+ *
+ * ## 解析一律剥未知键
+ * 与包内 api 契约的前向兼容同律(新键恒为加性)。同时这也是一条安全律:`secret` 只在 `active` 臂的形里 —— 别的臂即使收到也剥掉,
+ * 解析出的值里不会带着谁多塞的秘密。`secret` 是应答里唯一的秘密位;`credentialId` / `version` / `auditId` 是不带值的审计位。
+ */
+import { z } from "zod";
+import { INTEGER } from "../integer.js";
+import { buildQuotedIssue } from "../quoted-issue.js";
+import { SANDBOX_GIT_MAX_ORIGINS, SandboxGitOrigin, SandboxGitOriginList } from "../sandbox-git.js";
+import { PRINCIPAL_MAX_LENGTH, PrincipalIncarnation } from "./auth-bridge.js";
+// ── 逐 origin 判定序表 ─────────────────────────────────────────────────────────────────────────────────────────────
+/**
+ * 逐 origin 判定序表(11 行,序即判定序)。每行 `{ state, reason? }`:命中这一行的 origin 的应答是这个状态与这个原因。
+ * 条件(各行什么事实命中)见 `docs/CONSUMER-INTEGRATION.md` 的判定序表;`active` 是兜底行(行 `active` 且刷新不成问题),没有原因。
+ * 加一行 / 改序都是改契约:状态词、原因词、应答臂的原因值域、类型全部随这一张表走。
+ */
+export const SANDBOX_GIT_ORIGIN_VERDICTS = [
+    { state: "insecure_transport", reason: "not_https" },
+    { state: "not_offered", reason: "not_in_registry" },
+    { state: "not_connected", reason: "no_row" },
+    { state: "not_connected", reason: "revoked" },
+    { state: "needs_reauth", reason: "revoking" },
+    { state: "needs_reauth", reason: "suspended" },
+    { state: "needs_reauth", reason: "row_needs_reauth" },
+    { state: "needs_reauth", reason: "integrity_failed" },
+    { state: "needs_reauth", reason: "refresh_rejected" },
+    { state: "temporarily_unavailable", reason: "refresh_unavailable" },
+    { state: "active" },
+];
+/** 状态词表:判定序表里状态首次出现的次序。 */
+export const SANDBOX_GIT_ORIGIN_STATES = [...new Set(SANDBOX_GIT_ORIGIN_VERDICTS.map((v) => v.state))];
+/** 原因词表:判定序表里原因出现的次序(= 判定序)。 */
+export const SANDBOX_GIT_ORIGIN_REASONS = SANDBOX_GIT_ORIGIN_VERDICTS.flatMap((v) => ("reason" in v ? [v.reason] : []));
+/** 判定序表里某个状态下的原因词,按表序。 */
+function reasonsOf(state) {
+    return SANDBOX_GIT_ORIGIN_VERDICTS.flatMap((v) => (v.state === state && "reason" in v ? [v.reason] : []));
+}
+// ── 公共字段 ───────────────────────────────────────────────────────────────────────────────────────────────────────
+/** 本模块里每个数值位(毫秒时刻、凭据行版本)的形:非负安全整数 —— 包内的整数判据 + 安全整数上界;浮点、负数、超出安全整数的都不是。 */
+const SafeCount = INTEGER.nonnegative().max(Number.MAX_SAFE_INTEGER);
+const NonEmptyString = z.string().min(1);
+/**
+ * 请求与应答都带的「这是谁的 run」字段:主体(长度界同令牌 `sub` 的界,{@link PRINCIPAL_MAX_LENGTH})、化身号({@link PrincipalIncarnation},与令牌 `sub_inc` 同一只 schema)、
+ * scope(非空串 —— 与 `readTokenScope` 读 token 声明的规则同一条,不另立 slug 规则)。应答里这三键是**回显**,等不等于请求由收方核。
+ */
+const RunIdentity = {
+    principal: z.string().min(1).max(PRINCIPAL_MAX_LENGTH),
+    principalInc: PrincipalIncarnation,
+    scope: NonEmptyString,
+};
+// ── ① 申领句柄、② 兑换:请求与句柄应答 ───────────────────────────────────────────────────────────────────────────
+/** 申领 `sandbox_git` 句柄的请求体。`origins` = 要取凭据的 origin(规范形、1–16 个、两两不同;http origin 也收 —— 中心对它答判定序第 1 行);`sid` = 会话 id(审计标签,不是安全边界)。 */
+export const SandboxGitCredentialRequest = z.object({
+    kind: z.literal("sandbox_git"),
+    ...RunIdentity,
+    origins: SandboxGitOriginList.min(1),
+    sid: NonEmptyString,
+});
+/** 申领成功的应答:句柄(不透明串,一次性)与它的到期时刻(毫秒)。与凭据种类无关。 */
+export const CredentialHandleAnswer = z.object({ handle: NonEmptyString, expiresAt: SafeCount });
+/** 兑换请求:只有句柄 —— 调用方凭据在传输层,不在体里。与凭据种类无关。 */
+export const CredentialResolveRequest = z.object({ handle: NonEmptyString });
+// ── 应答:逐 origin 一行 ─────────────────────────────────────────────────────────────────────────────────────────
+/** 非 `active` 状态的应答臂:`{ origin, state, reason }`,`reason` 的值域 = 判定序表里该状态的行。 */
+function verdictArm(state) {
+    return z.object({ origin: SandboxGitOrigin, state: z.literal(state), reason: z.enum(reasonsOf(state)) });
+}
+/**
+ * 一个 origin 的应答行,按 `state` 判别。键集(判定序表之上的形):
+ *  · `active` 独有 `credentialId` `version` `username` `secret` `expiresAt`(OAuth 令牌:到期毫秒;个人访问令牌:`null`);没有 `reason`;
+ *  · `needs_reauth`(序 5–9)带 `credentialId`(不带值的审计位);
+ *  · 其余只有 `origin` / `state` / `reason`。
+ * 多给的键一律剥掉(见模块头注)。
+ */
+export const SandboxGitOriginAnswer = z.discriminatedUnion("state", [
+    verdictArm("insecure_transport"),
+    verdictArm("not_offered"),
+    verdictArm("not_connected"),
+    verdictArm("needs_reauth").extend({ credentialId: NonEmptyString }),
+    verdictArm("temporarily_unavailable"),
+    z.object({
+        origin: SandboxGitOrigin,
+        state: z.literal("active"),
+        credentialId: NonEmptyString,
+        version: SafeCount,
+        username: NonEmptyString,
+        secret: NonEmptyString,
+        expiresAt: SafeCount.nullable(),
+    }),
+]);
+/**
+ * 取值应答(200)。`principal` / `principalInc` / `scope` 是请求的**回显**;`answeredAt`(应答时刻)、`cacheUntil`(句柄到期,收方不得把凭据缓存过它)与行里的 `expiresAt`
+ * 是**同一只钟**(中心的)给的毫秒 —— 收方只该用它们的**差**,不拿它们和自己的钟比。`auditId` = 审计行 id(不带值)。
+ * `origins` 与请求逐条对应(同序同长)是收方要核的事,本形只钉 1–{@link SANDBOX_GIT_MAX_ORIGINS} 条。
+ */
+export const SandboxGitCredentialAnswer = z.object({
+    kind: z.literal("sandbox_git"),
+    ...RunIdentity,
+    auditId: NonEmptyString,
+    answeredAt: SafeCount,
+    cacheUntil: SafeCount,
+    origins: z.array(SandboxGitOriginAnswer).min(1).max(SANDBOX_GIT_MAX_ORIGINS),
+});
+// ── 整次拒答 ───────────────────────────────────────────────────────────────────────────────────────────────────────
+/** `permanence` 两词:`terminal` = 不按定时重试;`transient` = 退避重试。 */
+export const SANDBOX_GIT_PERMANENCE = ["terminal", "transient"];
+/**
+ * 整次拒答词 → 它的 HTTP 状态集(中心答这个词时用其一)与 `permanence`。**一个错误词的 permanence 是固定的**,拒体里再带一份只为让收方不必查表 ——
+ * 两处不一致就是畸形应答({@link SandboxGitCredentialRefusal} 拒)。收方怎么处置某个词(例如哪些 terminal 可由用户动作恢复)是收方的状态机,不在这里。
+ */
+export const SANDBOX_GIT_REFUSALS = {
+    caller_not_admitted: { statuses: [401, 403], permanence: "terminal" },
+    scope_mismatch: { statuses: [403], permanence: "terminal" },
+    incarnation_mismatch: { statuses: [403], permanence: "terminal" },
+    request_invalid: { statuses: [400], permanence: "terminal" },
+    principal_not_live: { statuses: [403], permanence: "terminal" },
+    delegation_required: { statuses: [403], permanence: "terminal" },
+    vault_disabled: { statuses: [503], permanence: "terminal" },
+    vault_frozen: { statuses: [503], permanence: "terminal" },
+    handle_invalid: { statuses: [401], permanence: "transient" },
+    vault_unavailable: { statuses: [503], permanence: "transient" },
+};
+/** 整次拒答词表(运行期;表的键,按表序)。 */
+export const SANDBOX_GIT_REFUSAL_ERRORS = Object.keys(SANDBOX_GIT_REFUSALS);
+/** 整次拒答的体:`{ error, permanence, message }`。`message` 是中心的诊断句(收方不据它判,可为空串)。 */
+export const SandboxGitCredentialRefusal = z
+    .object({
+    error: z.enum(SANDBOX_GIT_REFUSAL_ERRORS),
+    permanence: z.enum(SANDBOX_GIT_PERMANENCE),
+    message: z.string(),
+})
+    .refine((body) => SANDBOX_GIT_REFUSALS[body.error].permanence === body.permanence, buildQuotedIssue `permanence must be the one the refusal table gives for this error`);

package/dist/api/scopes.js

@@ -47,6 +47,7 @@ import { z } from "zod";
 import { INTEGER } from "../integer.js";
 import { buildQuotedIssue, fixed } from "../quoted-issue.js";
 import { USER_ROLES } from "../config-fns.js";
+import { ownDeclaredValueOf } from "../own-key-read.js";
 import { ACCESS_TOKEN_TTL_SECONDS } from "./auth.js";
 // ── constants ────────────────────────────────────────────────────────────────────────────────────────────
 /** The reserved default scope. Always exists. */
@@ -230,5 +231,8 @@ export const TOKEN_SCOPE_REFUSALS = ["scope_claim_missing"];
  * 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 function readTokenScope(claims) {
-    return typeof claims.scope === "string" && claims.scope.length > 0 ? { scope: claims.scope } : { refused: "scope_claim_missing" };
+    // the claim is read from the claims' OWN keys (a polluted `Object.prototype.scope` is not a scope the token carries); a claim that cannot be read is a claim that is missing
+    const read = ownDeclaredValueOf(claims, "scope");
+    const scope = read.ok ? read.value : undefined;
+    return typeof scope === "string" && scope.length > 0 ? { scope } : { refused: "scope_claim_missing" };
 }

package/dist/atomic-write.d.ts

@@ -29,3 +29,18 @@ export declare function writeFileAtomic(target: string, text: string, kind: Atom
  * 入参 `dir` 是已解析到真目录的路径;返回目录的权限位是否让本进程能增删其中的目录项。
  */
 export declare function directoryAdmitsWrite(dir: string): boolean;
+/** 新建目录的模式:仅属主可读写进(引擎的目录信任判官要求路径上的组件不得组 / 他人可写;0o700 在任何 umask 下都过)。 */
+export declare const OWNER_ONLY_DIRECTORY_MODE = 448;
+/**
+ * 原子地**不存在才建** `target`(见文件头「不存在才建」):建成 ⇒ `"created"`;目标名已在(只有 `EEXIST`)⇒ `"present"`(一字不动)。
+ * 临时文件独占建出、写完、fsync({@link writeTempExclusive})后 `link` 成目标名。模式 = `kind` 在表里的新建模式经进程 umask(目标按定义不在,没有「已有的模式」可沿用)。
+ * 临时文件建不出 / 写不完 / fsync 不了 ⇒ 抛 {@link FsFailure}(落点「往目录里写临时文件」,与 {@link writeFileAtomic} 建临时文件失败同落点同句);`link` 的别的失败原样抛
+ * (调用方经 `fsFailureMessage` 取句)。父目录须已存在。
+ */
+export declare function createFileExclusive(target: string, text: string, kind: AtomicFileClass): "created" | "present";
+/**
+ * 目录不在就建(连同缺的上级):**逐级** mkdir、每建一级立刻 chmod 到 {@link OWNER_ONLY_DIRECTORY_MODE} —— 模式恰是它,不经 umask(umask 0777 下一次性的递归 mkdir 会先建出
+ * 一级 0000 的目录、再也进不去建下一级)。本进程建了 `dir` ⇒ `"created"`;`dir` 已在(或恰被别的进程同时建成)⇒ `"present"`(它的模式一位不动)。
+ * 路径上有一节不是目录 ⇒ 抛。
+ */
+export declare function ensureOwnerOnlyDirectory(dir: string): "created" | "present";