@sema-agent/settings-schema 14.5.0 → 14.7.0

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.js

@@ -21,10 +21,11 @@
  * 悬空链接在读阶段与写阶段是**同一句**({@link danglingSymlinkSentence})。
  *
  * ## 写失败(12.0.0;句子归文件系统失败句的唯一铸点)
- * 两步各一句({@link FsFailure},句子在 `./fs-failure`):临时文件建不出 ⇒ 「cannot write into directory <dir> (<errno>): …」(点名目录 —— 目录不可写时
- * 文件本身没错);`rename` 失败 ⇒ 「cannot replace <file> (<errno>): …」(点名真文件)。认得的 errno 给对应出路,别的给 Node 自己的句子;`code` / `cause` 留着。
- * 可写目录里的只读文件照常写得进(`rename` 换的是目录项)。权限类 errno 的出路顺序要一个只有 Node 一侧读得到的事实 —— 失败那一刻目录的权限位对本进程是否可写({@link directoryAdmitsWrite},模式判在本文件、与模式表同处),
- * 写器在建临时文件那一步读了经落点递给铸点(`EPERM` ∧ 可写 ⇒ 真因是不可变标志,首选出路是清标志;否则先 chmod);`rename` 那一步不读 —— 临时文件刚在同目录建成,可写是已证明的事实,铸点自己给。
+ * 三步各一句({@link FsFailure},句子在 `./fs-failure`):临时文件建不出 ⇒ 「cannot write into directory <dir> (<errno>): …」(点名目录 —— 目录不可写时
+ * 文件本身没错);沿用原模式的文件给临时文件设模式失败 ⇒ 「cannot set the mode of <file> (<errno>): …」(点名设模式这一步 —— 文件系统不让改模式,目录没有问题);`rename` 失败 ⇒ 「cannot replace <file> (<errno>): …」(点名真文件)。
+ * 认得的 errno 给对应出路,别的给 Node 自己的句子;`code` / `cause` 留着。
+ * 可写目录里的只读文件照常写得进(`rename` 换的是目录项)。权限类 errno 的出路要一个只有 Node 一侧读得到的事实 —— 失败那一刻目录的权限位对本进程是否可写({@link directoryAdmitsWrite},模式判在本文件、与模式表同处),
+ * 写器在建临时文件那一步读了经落点递给铸点(`EPERM` ∧ 可写 ⇒ 真因是不可变标志,首选出路是清标志;`EACCES` ∧ 可写 ⇒ 真因是 ACL / 安全模块;不可写 ⇒ 先让目录可写);`chmod` / `rename` 那两步不读 —— 临时文件刚在同目录建成,可写是已证明的事实,铸点自己给。
  */
 import { randomBytes } from "node:crypto";
 import { chmodSync, lstatSync, readlinkSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
@@ -91,8 +92,10 @@ export function writeFileAtomic(target, text, kind) {
     let site = { landing: "dir-create-temp", path: tmp };
     try {
         writeFileSync(tmp, text, { encoding: "utf8", mode: kept ?? spec.newMode });
-        if (kept !== undefined)
+        if (kept !== undefined) {
+            site = { landing: "chmod", path: real }; // the temporary file now exists in the directory: a failure from here on is not the directory's; it names the step (the real file whose mode is being kept)
             chmodSync(tmp, kept); // a kept mode is restored exactly (the creation mode above went through the umask)
+        }
         site = { landing: "rename", path: real };
         renameSync(tmp, real);
     }
@@ -103,8 +106,8 @@ export function writeFileAtomic(target, text, kind) {
         catch {
             /* 临时文件没建成:没什么可清 */
         }
-        // the sentence names the step that failed and its way out (`./fs-failure`, the one mint); the way-out order needs one Node-side fact — do the directory's mode bits admit this process —
-        // read only at the create step: by the time `rename` runs the temporary file has just been created in the same directory, so "writable" is proven there and the mint says so itself
+        // the sentence names the step that failed and its way out (`./fs-failure`, the one mint); the way-out table needs one Node-side fact — do the directory's mode bits admit this process —
+        // read only at the create step: by the time `chmod` / `rename` run the temporary file has just been created in the same directory, so "writable" is proven there and the mint says so itself
         throw new FsFailure(site.landing === "dir-create-temp" ? { ...site, directoryWritable: directoryAdmitsWrite(dir) } : site, e);
     }
 }

package/dist/bundle.d.ts

@@ -1,4 +1,4 @@
-import { type PortableDomain } from "./file-store.js";
+import { type PortableDomain } from "./portable-domains.js";
 import type { ConfigReader } from "./reader.js";
 /** A bundle carries PORTABLE domains only — the non-portable ones (`NON_PORTABLE_DOMAIN_REASONS`: workers / hosts / systems / projects /
  *  entitlement) never travel, and the three bundle functions are that table's other face (types narrow to {@link PortableDomain}; a

package/dist/bundle.js

@@ -9,7 +9,7 @@
  * Node-only (writeBundle/readBundle touch the filesystem) → imported via `@sema-agent/settings-schema/node`.
  */
 import { writeDomainFile } from "./file-edit.js";
-import { PORTABLE_DOMAINS } from "./file-store.js";
+import { PORTABLE_DOMAINS } from "./portable-domains.js";
 import { configDPath, readConfigDFile, refuseRetiredDomainFiles } from "./config-d-file.js";
 /** The runtime guard of the same rule (a name that is not even a domain is refused first — no path traversal). */
 function assertPortable(d) {

package/dist/config-d-file.js

@@ -12,7 +12,8 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { refuseRetiredDomain, sanitizeZodError } from "./config-fns.js";
-import { isPlainJsonObject } from "./plain-json-object.js";
+import { UNINSPECTABLE, guardedSafeParse } from "./own-key-read.js";
+import { jsonShapeOf } from "./plain-json-object.js";
 import { REMOTE_EXEC_DOCUMENT, RemoteExecSpec } from "./remote-exec.js";
 import { RETIRED_DOMAINS, isDomainName, isRetiredDomainName } from "./types.js";
 /** 一份 `config.d` 文档写盘的**文本形** —— 两格缩进的 JSON 加一个换行。写域文件(`writeDomainFile`)、写 `remote-exec.json`(`writeRemoteExec`)与目录迁移写回
@@ -23,16 +24,12 @@ export function configDDocumentText(value) {
 /** 判一份 remote-exec 文档的值(`RemoteExecSpec`),错误**脱敏**(zod 会回显出错的值 —— 粘错位置的密钥不许随抛出的错走);反射访问抛(恶意 getter /
  *  Proxy)⇒ 定句。`loadRemoteExec` / `writeRemoteExec` 与目录迁移的整文档终判调同一只。 */
 export function parseRemoteExecDocument(raw) {
-    let r;
-    try {
-        r = RemoteExecSpec.safeParse(raw);
-    }
-    catch {
-        throw new Error("invalid remoteExec (a value could not be read during validation)");
-    }
-    if (r.success)
-        return r.data;
-    throw sanitizeZodError(r.error);
+    const judged = guardedSafeParse(() => RemoteExecSpec.safeParse(raw), sanitizeZodError); // 错误对象的构造与脱敏都在守护里(zod 4.6 首读才拼句子)
+    if (!judged.ok)
+        throw new TypeError("invalid remoteExec (a value could not be read during validation)");
+    if (judged.value.success)
+        return judged.value.data;
+    throw judged.value.error;
 }
 /** `<root>/config.d/<名>.json` 的路径 —— 名字的判也在这里(**一处**):不是配置域也不是 retired 域 ⇒ 拒(不拿用户给的名拼路径,防 `../` 穿越)。 */
 export function configDPath(root, name) {
@@ -64,11 +61,32 @@ export function judgeConfigDText(name, text, file) {
  *  非朴素对象 ⇒ 抛。{@link judgeConfigDText} 的最后一道判就是这只(文本解析出来之后过它),所以「不是对象」一种坏形一句话,不论文档是从文件文本来的还是调用方直接给的;
  *  `label` = 句首的称呼(文本路径给文件的真实路径,值路径给 `the <名> document`)。 */
 export function judgeConfigDValue(name, value, label) {
-    if (!isPlainJsonObject(value)) {
-        const kind = value === null ? "null" : Array.isArray(value) ? "array" : typeof value === "object" ? "non-plain object" : typeof value;
-        throw new Error(`${label} must be a JSON object (got ${kind}) — ${documentWayOut(name)}`);
+    const shape = jsonShapeOf(value);
+    if (shape === "plain")
+        return value;
+    // `shape` is narrowed to the five non-plain words: an exhaustive switch (a sixth word is a compile error here)
+    let kind;
+    switch (shape) {
+        case "null":
+            kind = "null";
+            break;
+        case "array":
+            kind = "array";
+            break;
+        case "non_plain_object":
+            kind = typeof value === "function" ? "function" : "non-plain object";
+            break;
+        case "uninspectable": // 读不出(撤销的 Proxy / 陷阱抛)不是「不是对象」:调用方给的对象读不出是调用方的错 ⇒ `TypeError`(v14.6.0:引擎对它抛的就是 TypeError),句子带全包唯一那一句
+            throw new TypeError(`${label} must be a JSON object (got ${UNINSPECTABLE}) — ${documentWayOut(name)}`);
+        case "primitive":
+            kind = typeof value;
+            break;
+        default: {
+            const unhandled = shape;
+            throw new Error(`judgeConfigDValue: unhandled shape ${String(unhandled)}`);
+        }
     }
-    return value;
+    throw new Error(`${label} must be a JSON object (got ${kind}) — ${documentWayOut(name)}`);
 }
 /** 读一个 `config.d/<名>.json`:不存在(ENOENT)⇒ `undefined`;在场 ⇒ {@link judgeConfigDText}。 */
 export async function readConfigDFile(root, name) {

package/dist/config-dir-migration.js

@@ -31,6 +31,7 @@ import { z } from "zod";
 import { formatConfigPath, parseDomain } from "./config-fns.js";
 import { configDDocumentText, judgeConfigDText, judgeConfigDValue, parseRemoteExecDocument } from "./config-d-file.js";
 import { fsFailureMessage } from "./fs-failure.js";
+import { isPlainJsonObject } from "./plain-json-object.js";
 import { migrateStoredDocuments } from "./one-time-migrations.js";
 import { REMOTE_EXEC_DOCUMENT } from "./remote-exec.js";
 import { RUNTIME_LIFT_TARGETS } from "./runtime-lift-targets.js";
@@ -150,7 +151,7 @@ function migrateCovered(caller, docs, covered) {
  * 覆盖面外的键不读、不判、不进结果;覆盖面内在场(非 `undefined`)的文档必须是 JSON 对象,否则回 `unreadable`(不抛)。`docs` 不是对象 / 覆盖面拼错 ⇒ `TypeError`(调用方的错,不是数据的错)。
  */
 export function migrateConfigDocuments(docs, opts) {
-    if (docs === null || typeof docs !== "object" || Array.isArray(docs))
+    if (!isPlainJsonObject(docs))
         throw new TypeError("migrateConfigDocuments: `docs` must be a { document: value } object");
     const covered = coveredDocuments("migrateConfigDocuments", opts.documents);
     const present = {};