@sema-agent/server 7.101.0 → 7.102.0

package/dist/center-credential-renewer.js

@@ -0,0 +1,359 @@
+import { createHash, randomBytes } from "node:crypto";
+import { closeSync, fchmodSync, fsyncSync, openSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { CENTER_CREDENTIAL_ENV, CenterCredentialEnvelope, parseCenterCredentialFile } from "@sema-agent/settings-schema";
+import { ACCESS_TOKEN_TTL_SECONDS, OAuthErrorResponse, TokenGrantResponse } from "@sema-agent/settings-schema/api/auth";
+import { CENTER_PULL_TIMEOUT_MS, centerTokenRefresh } from "./config-center/center-request.js";
+export const CENTER_CREDENTIAL_RENEW_LEAD_KEY = "CENTER_CREDENTIAL_RENEW_LEAD_MS";
+export const CENTER_CREDENTIAL_RENEW_LEAD_DEFAULT_MS = 5 * 60_000;
+export const CENTER_CREDENTIAL_RENEW_LEAD_MIN_MS = CENTER_PULL_TIMEOUT_MS;
+export const CENTER_CREDENTIAL_RENEW_LEAD_MAX_MS = (ACCESS_TOKEN_TTL_SECONDS * 1000) / 2;
+export function parseCenterCredentialRenewLeadMs(raw) {
+    if (raw === undefined || raw.trim() === "")
+        return CENTER_CREDENTIAL_RENEW_LEAD_DEFAULT_MS;
+    const n = Number(raw);
+    if (n === 0)
+        return 0;
+    if (!Number.isSafeInteger(n) || n < CENTER_CREDENTIAL_RENEW_LEAD_MIN_MS || n > CENTER_CREDENTIAL_RENEW_LEAD_MAX_MS) {
+        throw new Error(`env ${CENTER_CREDENTIAL_RENEW_LEAD_KEY}="${raw}" must be 0 (renewal off: the sign-in envelope is only read) or an INTEGER number of MILLISECONDS in ` +
+            `[${CENTER_CREDENTIAL_RENEW_LEAD_MIN_MS}, ${CENTER_CREDENTIAL_RENEW_LEAD_MAX_MS}] — how long before the access token expires the engine renews it. ` +
+            `Below the floor not even one refresh request (timeout ${CENTER_PULL_TIMEOUT_MS} ms) fits before expiry; above the ceiling (half the ${ACCESS_TOKEN_TTL_SECONDS}s access-token lifetime) ` +
+            `every freshly minted token is already due, so renewal would spin. Unset = ${CENTER_CREDENTIAL_RENEW_LEAD_DEFAULT_MS}.`);
+    }
+    return n;
+}
+export function buildCenterCredentialHealthView(health, renewer) {
+    const renewal = renewer?.renewal();
+    const expiresAt = renewer?.sessionExpiresAt();
+    const renewalCell = renewal === undefined || renewal.state === "idle"
+        ? undefined
+        : { state: renewal.state, reason: renewal.reason, since: renewal.since, ...(expiresAt !== undefined ? { expiresAt: new Date(expiresAt).toISOString() } : {}) };
+    if (health.state === "ok")
+        return renewalCell === undefined ? undefined : { state: "ok", renewal: renewalCell };
+    return { state: "unreadable", failure: health.failure, since: health.since, failures: health.failures, ...(renewalCell !== undefined ? { renewal: renewalCell } : {}) };
+}
+const digest16 = (s) => createHash("sha256").update(s, "utf8").digest("hex").slice(0, 16);
+function readFileNow(path) {
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch (err) {
+        const code = err instanceof Error && "code" in err && typeof err.code === "string" ? err.code : "read error";
+        return code === "ENOENT" ? { kind: "no-session" } : { kind: "unreadable", code };
+    }
+    const file = parseCenterCredentialFile(text);
+    return file.kind === "envelope" ? { kind: "session", envelope: file.envelope, refreshDigest: digest16(file.envelope.refreshToken) } : { kind: "no-session" };
+}
+const TMP_RANDOM_BYTES = 6;
+const tmpNameFor = (path) => `.${basename(path)}.${process.pid}.${randomBytes(TMP_RANDOM_BYTES).toString("hex")}.tmp`;
+const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const tmpResiduePattern = (path) => new RegExp(`^\\.${escapeRegExp(basename(path))}\\.\\d+\\.[0-9a-f]{${TMP_RANDOM_BYTES * 2}}\\.tmp$`);
+function prepareTmp(path, envelope, discard, onCleanupFailure) {
+    const tmp = join(dirname(path), tmpNameFor(path));
+    const fd = openSync(tmp, "wx", 0o600);
+    let written = false;
+    try {
+        fchmodSync(fd, 0o600);
+        writeFileSync(fd, `${JSON.stringify(envelope)}\n`, "utf8");
+        fsyncSync(fd);
+        written = true;
+    }
+    finally {
+        try {
+            closeSync(fd);
+        }
+        catch (err) {
+            onCleanupFailure("close", err);
+        }
+        if (!written)
+            discard(tmp);
+    }
+    return tmp;
+}
+function sameOrigin(a, b) {
+    return new URL(a).origin === new URL(b).origin;
+}
+const BACKOFF_BASE_MS = 1000;
+function sessionExpiryOf(read) {
+    if (read.ok)
+        return read.kind === "user-session" ? read.expiresAt : undefined;
+    return read.failure === "expired" ? read.expiresAt : undefined;
+}
+export function createCenterCredentialRenewer(deps) {
+    const { source, centerUrl, leadMs, logger } = deps;
+    if (source.origin.from !== "file")
+        throw new Error(`center credential renewer needs the ${CENTER_CREDENTIAL_ENV.tokenFile} form (got ${source.origin.from})`);
+    const path = source.origin.path;
+    const now = deps.now ?? Date.now;
+    const tickMs = Math.min(Math.max(leadMs / 2, 1000), 60_000);
+    let renewal = { state: "idle" };
+    let subject;
+    let held;
+    let inFlight = false;
+    let stopped = false;
+    const stranded = new Set();
+    let cleanupWarned = false;
+    let quietUntil = 0;
+    let lastExpiresAt;
+    let unavailableStreak = (() => {
+        const h = source.health();
+        return h.state === "unreadable" ? h.failure : undefined;
+    })();
+    const expiryField = () => (lastExpiresAt !== undefined ? { expiresAt: new Date(lastExpiresAt).toISOString() } : {});
+    const errCode = (err, fallback) => (err instanceof Error && "code" in err && typeof err.code === "string" ? err.code : err instanceof Error ? err.name : fallback);
+    const reportCleanup = (op, err) => {
+        if (cleanupWarned)
+            return;
+        cleanupWarned = true;
+        logger.warn("center_credential_tmp_cleanup_failed", {
+            op,
+            code: errCode(err, `${op} error`),
+            note: "a temporary copy of the credential (0600, next to the credential file) may be left behind; the renewal outcome is unaffected. It is removed after the next successful rewrite or at the next start; warned once per process",
+        });
+    };
+    const discardTmp = (tmp) => {
+        try {
+            rmSync(tmp, { force: true });
+            stranded.delete(tmp);
+            return true;
+        }
+        catch (err) {
+            stranded.add(tmp);
+            reportCleanup("remove", err);
+            return false;
+        }
+    };
+    {
+        const dir = dirname(path);
+        const pattern = tmpResiduePattern(path);
+        let names = [];
+        try {
+            names = readdirSync(dir).filter((n) => pattern.test(n));
+        }
+        catch (err) {
+            reportCleanup("scan", err);
+        }
+        const removed = names.filter((name) => discardTmp(join(dir, name))).length;
+        if (removed > 0)
+            logger.info("center_credential_tmp_residue_removed", { count: removed });
+    }
+    const loudness = (read) => {
+        if (read.ok) {
+            unavailableStreak = undefined;
+            return;
+        }
+        if (unavailableStreak === read.failure)
+            return;
+        unavailableStreak = read.failure;
+        logger.warn("center_credential_unreadable", {
+            key: CENTER_CREDENTIAL_ENV.tokenFile,
+            failure: read.failure,
+            reason: read.reason,
+            note: "no center request carries this credential until the file holds a usable one again (each consumer takes its own failure arm); warned once per unavailability streak",
+        });
+    };
+    const reset = () => {
+        renewal = { state: "idle" };
+        subject = undefined;
+        held = undefined;
+    };
+    const reconcile = () => {
+        if (renewal.state === "idle" || inFlight)
+            return;
+        const file = readFileNow(path);
+        if (file.kind === "unreadable")
+            return;
+        if (file.kind === "no-session" || file.refreshDigest !== subject)
+            reset();
+    };
+    const settleTerminal = (reason, refreshDigest, fields) => {
+        renewal = { state: "failed", reason, since: now() };
+        subject = refreshDigest;
+        held = undefined;
+        if (reason === "issuer_mismatch") {
+            logger.warn("center_credential_issuer_mismatch", { ...fields, note: "the sign-in envelope was issued by a different center than SEMA_REGISTRY_URL — its refresh token is never sent there; the access token is used until it expires, then sign in again against this center" });
+            return;
+        }
+        logger.warn("center_credential_renew_failed", {
+            reason,
+            retrying: false,
+            ...fields,
+            ...expiryField(),
+            note: "this refresh token is not retried until the credential file changes (sign in again with the shell); center requests keep the current access token until it expires, then take their existing failure arms",
+        });
+    };
+    const settleRetrying = (reason, refreshDigest, fields) => {
+        const t = now();
+        const streak = renewal.state === "pending" && renewal.reason === reason ? renewal : undefined;
+        const attempts = streak === undefined ? 1 : streak.attempts + 1;
+        renewal = { state: "pending", reason, since: streak === undefined ? t : streak.since, attempts, retryAt: t + Math.min(BACKOFF_BASE_MS * 2 ** (attempts - 1), tickMs) };
+        subject = refreshDigest;
+        if (attempts === 1) {
+            logger.warn("center_credential_renew_failed", {
+                reason,
+                retrying: true,
+                ...fields,
+                ...expiryField(),
+                note: reason === "write_failed"
+                    ? "the center already rotated the refresh token; the new credential is kept in memory and the file rewrite is retried with backoff (the consumed token is never sent again); warned once per failure streak"
+                    : "retried with backoff on the next read / timer tick; warned once per failure streak",
+            });
+        }
+    };
+    const judgeRefusal = (usedDigest, reason, fields) => {
+        const file = readFileNow(path);
+        if (file.kind === "unreadable") {
+            settleRetrying("center_unavailable", usedDigest, { ...fields, readError: file.code });
+            return;
+        }
+        if (file.kind === "no-session" || file.refreshDigest !== usedDigest) {
+            reset();
+            return;
+        }
+        settleTerminal(reason, usedDigest, fields);
+    };
+    const persistHeld = (next, consumedDigest, expiresInSec) => {
+        held = next;
+        subject = consumedDigest;
+        let tmp;
+        try {
+            tmp = prepareTmp(path, next, discardTmp, reportCleanup);
+        }
+        catch (err) {
+            settleRetrying("write_failed", consumedDigest, { error: errCode(err, "write error") });
+            return;
+        }
+        const file = readFileNow(path);
+        if (file.kind !== "session" || file.refreshDigest !== consumedDigest) {
+            discardTmp(tmp);
+            if (file.kind === "unreadable") {
+                settleRetrying("write_failed", consumedDigest, { error: file.code });
+                return;
+            }
+            reset();
+            return;
+        }
+        try {
+            renameSync(tmp, path);
+        }
+        catch (err) {
+            discardTmp(tmp);
+            settleRetrying("write_failed", consumedDigest, { error: errCode(err, "rename error") });
+            return;
+        }
+        for (const leftover of [...stranded])
+            discardTmp(leftover);
+        reset();
+        lastExpiresAt = Date.parse(next.expiresAt);
+        quietUntil = now() + tickMs;
+        logger.info("center_credential_renewed", { expiresAt: next.expiresAt, ...(expiresInSec !== undefined ? { expiresInSec } : {}) });
+    };
+    const renewOnce = async () => {
+        if (held !== undefined && subject !== undefined) {
+            persistHeld(held, subject, undefined);
+            return;
+        }
+        const file = readFileNow(path);
+        if (file.kind !== "session")
+            return;
+        const { envelope, refreshDigest: usedDigest } = file;
+        if (subject !== undefined && subject !== usedDigest)
+            reset();
+        if (renewal.state === "failed")
+            return;
+        const expiresAt = Date.parse(envelope.expiresAt);
+        lastExpiresAt = expiresAt;
+        if (expiresAt - now() > leadMs) {
+            reset();
+            return;
+        }
+        if (!sameOrigin(envelope.issuer, centerUrl)) {
+            settleTerminal("issuer_mismatch", usedDigest, { issuerOrigin: new URL(envelope.issuer).origin, centerOrigin: new URL(centerUrl).origin });
+            return;
+        }
+        let res;
+        try {
+            res = await centerTokenRefresh(envelope.issuer, envelope.refreshToken, { timeoutMs: CENTER_PULL_TIMEOUT_MS, ...(deps.fetchImpl ? { fetchImpl: deps.fetchImpl } : {}) });
+        }
+        catch (err) {
+            settleRetrying("center_unavailable", usedDigest, { error: err instanceof Error ? err.name : "fetch error" });
+            return;
+        }
+        if (res.status >= 500 || res.status === 408 || res.status === 429) {
+            await res.body?.cancel();
+            settleRetrying("center_unavailable", usedDigest, { status: res.status });
+            return;
+        }
+        if (res.status !== 200) {
+            const oauth = OAuthErrorResponse.safeParse(await res.json().catch(() => undefined));
+            const oauthError = oauth.success ? oauth.data.error : undefined;
+            judgeRefusal(usedDigest, res.status === 400 && oauthError === "invalid_grant" ? "invalid_grant" : "rejected", { status: res.status, ...(oauthError !== undefined ? { oauthError } : {}) });
+            return;
+        }
+        const issuedAt = now();
+        const grant = TokenGrantResponse.safeParse(await res.json().catch(() => undefined));
+        if (!grant.success || !Number.isFinite(grant.data.expires_in) || grant.data.expires_in <= 0) {
+            judgeRefusal(usedDigest, "malformed_grant", { status: res.status });
+            return;
+        }
+        const next = CenterCredentialEnvelope.safeParse({
+            kind: envelope.kind,
+            accessToken: grant.data.access_token,
+            refreshToken: grant.data.refresh_token,
+            expiresAt: new Date(issuedAt + grant.data.expires_in * 1000).toISOString(),
+            issuer: envelope.issuer,
+        });
+        if (!next.success) {
+            judgeRefusal(usedDigest, "malformed_grant", { status: res.status });
+            return;
+        }
+        persistHeld(next.data, usedDigest, grant.data.expires_in);
+    };
+    const maybeRenew = (expiresAt) => {
+        if (leadMs === 0 || stopped || inFlight)
+            return;
+        const t = now();
+        if (renewal.state === "pending" && t < renewal.retryAt)
+            return;
+        if (held === undefined && (expiresAt - t > leadMs || t < quietUntil))
+            return;
+        inFlight = true;
+        void renewOnce()
+            .catch((err) => {
+            const error = { error: err instanceof Error ? err.message : String(err) };
+            if (held !== undefined && subject !== undefined) {
+                settleRetrying("write_failed", subject, error);
+                return;
+            }
+            const file = readFileNow(path);
+            settleRetrying("center_unavailable", file.kind === "session" ? file.refreshDigest : (subject ?? ""), error);
+        })
+            .finally(() => {
+            inFlight = false;
+        });
+    };
+    const unsubscribe = source.onRead((read) => {
+        loudness(read);
+        const expiresAt = sessionExpiryOf(read);
+        lastExpiresAt = expiresAt;
+        reconcile();
+        if (expiresAt !== undefined || held !== undefined)
+            maybeRenew(expiresAt ?? now());
+    });
+    const timer = leadMs > 0 ? setInterval(() => void source.read(), tickMs) : undefined;
+    timer?.unref();
+    if (leadMs > 0)
+        source.read();
+    return {
+        renewal: () => renewal,
+        sessionExpiresAt: () => lastExpiresAt,
+        stop() {
+            stopped = true;
+            if (timer !== undefined)
+                clearInterval(timer);
+            unsubscribe();
+        },
+    };
+}
+//# sourceMappingURL=center-credential-renewer.js.map

package/dist/center-credential.d.ts

@@ -1,15 +1,8 @@
+import { type CenterCredentialDeclaration } from "@sema-agent/settings-schema";
 /** 凭证种类闭集。新增一个种类 = 本文件与 `config-center/center-request.ts` 的穷举 switch 当场编译红。 */
-export type CenterCredentialKind = "pull-token" | "user-jwt" | "none";
-/** 凭证在哪里声明(env 形带值 —— 只在本模块内流转)。 */
-export type CenterCredentialDeclaration = {
-    readonly from: "env";
-    readonly token: string;
-} | {
-    readonly from: "file";
-    readonly path: string;
-} | {
-    readonly from: "absent";
-};
+export type CenterCredentialKind = "pull-token" | "user-jwt" | "user-session" | "none";
+/** 一次取值失败的成因闭集(见模块头注「四个成因」;boot 判决 {@link judgeCenterCredentialAtBoot} 对它穷举)。 */
+export type CenterCredentialFailure = "missing" | "malformed" | "multi_tenant_session" | "expired";
 /** 声明形的**非秘密**投影(进日志 / 拒因 / 未来的 caps 读面):env 形不带值。 */
 export type CenterCredentialOrigin = {
     readonly from: "env";
@@ -19,7 +12,11 @@ export type CenterCredentialOrigin = {
 } | {
     readonly from: "absent";
 };
-/** 一次取值的结果。`ok:false` 只有文件形会出现(env / absent 形的取值恒成功)。 */
+/**
+ * 一次取值的结果。`ok:false` 只有文件形会出现(env / absent 形的取值恒成功)。
+ * `identity` 是「此刻的凭证是谁」—— 成功恒在;失败时只有 `expired` 知道(信封还读得出 `sub`,只是令牌不许再出站),
+ * 其余失败 = 身份未知(见 {@link credentialIdentityNow})。
+ */
 export type CenterCredentialRead = {
     readonly ok: true;
     readonly kind: "pull-token";
@@ -31,19 +28,34 @@ export type CenterCredentialRead = {
     readonly kind: "user-jwt";
     readonly bearer: string;
     readonly identity: string;
+} | {
+    readonly ok: true;
+    readonly kind: "user-session";
+    readonly bearer: string;
+    readonly identity: string;
+    readonly expiresAt: number;
 } | {
     readonly ok: true;
     readonly kind: "none";
     readonly identity: string;
 } | {
     readonly ok: false;
+    readonly failure: Exclude<CenterCredentialFailure, "expired">;
     readonly reason: string;
+    readonly identity?: undefined;
+} | {
+    readonly ok: false;
+    readonly failure: "expired";
+    readonly reason: string;
+    readonly identity: string;
+    readonly expiresAt: number;
 };
-/** 健康态:最近一次取值的结果(caps `leaseHealth` 之类的读面读它,不自己再判)。 */
+/** 健康态:最近一次取值的结果(`/health.centerCredential` 经续签器模块的视图读它,不自己再判)。 */
 export type CenterCredentialHealth = {
     readonly state: "ok";
 } | {
     readonly state: "unreadable";
+    readonly failure: CenterCredentialFailure;
     readonly reason: string;
     readonly since: number;
     readonly failures: number;
@@ -56,31 +68,72 @@ export interface CenterCredentialSource {
     /** 每次出站请求调用一次;文件形每次都读文件。 */
     read(): CenterCredentialRead;
     health(): CenterCredentialHealth;
+    /**
+     * S-698:每次取值之后**同步**回调一次(入参 = 这次的结果,已记进健康态)。续签器的唯一触发口(设计 §2「每次取值后,
+     * 读到 user-session 信封且在提前量内 ⇒ 排队一次续签」)。返回退订。回调不许抛(抛 = 这次取值跟着抛,响亮)。
+     */
+    onRead(listener: (read: CenterCredentialRead) => void): () => void;
 }
-/** 凭证文件此刻不可读 / 为空。中心请求装配点(`center-request.ts`)取值失败时抛它,各消费方按自己的
+/** 凭证此刻取不到(文件不可读 / 读不成 / 过期 / 多租户拒)。中心请求装配点(`center-request.ts`)取值失败时抛它,各消费方按自己的
  *  失败臂处置(拉配置保 LKG、caps fail-closed、租约走「鉴权失败」响亮臂 …),**不发一个空 bearer 出去**。 */
 export declare class CenterCredentialUnavailableError extends Error {
     readonly reason: string;
     constructor(reason: string);
 }
-export declare const CENTER_TOKEN_ENV = "SEMA_REGISTRY_TOKEN";
-export declare const CENTER_TOKEN_FILE_ENV = "SEMA_REGISTRY_TOKEN_FILE";
 /**
- * 读两个声明键。两个都非空 ⇒ throw(boot 拒启,拒因点名二选一)。空串 = 未设(与 7.98.0 之前
- * `SEMA_REGISTRY_TOKEN || ""` 的读法一致)。文件路径在这里解析成绝对路径(之后 cwd 变了也读同一个文件)。
+ * 凭证来源的构造入参:settings-schema 的声明形,文件形**必须**带上本部署的租户姿态(多租户拒人的会话信封,见模块头注)——
+ * 姿态只在文件形有意义(env 值形是部署注入的拉取令牌,永远不是信封),所以只在那一臂上必填:漏传 = 编译红,不是静默单租户。
+ */
+export type CenterCredentialSourceSpec = Exclude<CenterCredentialDeclaration, {
+    from: "file";
+}> | {
+    readonly from: "file";
+    readonly path: string;
+    readonly multiTenant: boolean;
+};
+/**
+ * 读两个声明键 —— 判定全交 settings-schema 的判官 `judgeCenterCredentialDeclaration`(S-742:二选一规则的**唯一**实现;空串 = 未设、
+ * 不 trim;两个都设 ⇒ throw,boot 拒启,拒句点名两个键、不回显值)。本仓只多读方自己的那一步:文件路径按本进程 cwd 解析成绝对
+ * 路径(之后 cwd 变了也读同一个文件 —— 纯契约不碰 `node:path`,这一步归读方)。
  */
-export declare function readCenterCredentialDeclaration(env?: NodeJS.ProcessEnv): CenterCredentialDeclaration;
+export declare function readCenterCredentialDeclaration(env?: Readonly<Record<string, string | undefined>>): CenterCredentialDeclaration;
 /** 拉取令牌形的身份 = worker(拉取令牌代表 worker,不是人)。种类判别与 formatVersion 1 LKG 的一次性迁移
  *  (`config-lkg.ts` `migrateV1Lkg`:v1 信封只记 worker,只有这一形的身份推得出来)共用这一只。 */
 export declare function pullTokenIdentity(worker: string | undefined): string;
 /**
  * 凭证来源工厂(活对象:文件形每次取值读盘并记健康态)。`worker` = `SEMA_REGISTRY_WORKER`(拉取令牌形的身份)。
- * `readFile` 只为测试注入。
+ * `readFile` / `now` 只为测试注入。
  */
-export declare function createCenterCredentialSource(declaration: CenterCredentialDeclaration, worker: string | undefined, deps?: {
+export declare function createCenterCredentialSource(spec: CenterCredentialSourceSpec, worker: string | undefined, deps?: {
     readFile?: (path: string) => string;
     now?: () => number;
 }): CenterCredentialSource;
+/** boot 期一次取值的判决(闭集,对 {@link CenterCredentialFailure} 穷举 —— 加一个成因不补臂 = 编译红)。 */
+export type CenterCredentialBootVerdict = {
+    readonly verdict: "serve";
+} | {
+    readonly verdict: "loud";
+    readonly failure: "missing" | "expired";
+    readonly reason: string;
+    readonly effect: string;
+} | {
+    readonly verdict: "refuse";
+    readonly code: CenterCredentialRefusalCode;
+    readonly sentence: string;
+};
+/** 拒启码(拼法随 `config.*` 家族,按**规则**命名):出现在拒启句的方括号里。 */
+export declare const CENTER_CREDENTIAL_REFUSAL_CODES: {
+    readonly malformed: "config.center_credential_malformed";
+    readonly multi_tenant_session: "config.center_credential_user_session_multi_tenant";
+};
+export type CenterCredentialRefusalCode = (typeof CENTER_CREDENTIAL_REFUSAL_CODES)[keyof typeof CENTER_CREDENTIAL_REFUSAL_CODES];
+/**
+ * S-698 —— boot 读到的凭证怎么处置(`boot/config-center.ts` 执行,规则只在这里):
+ *  · `missing` / `expired` ⇒ 响亮(error 级一行),照常起服 —— 前者是「此刻没有凭证」(登出形,文件出现即恢复),
+ *    后者续签器立刻续签;
+ *  · `malformed` / `multi_tenant_session` ⇒ **拒启**,拒句带码、点名文件键,不回显内容(`reason` 由本模块铸,本来就不含内容)。
+ */
+export declare function judgeCenterCredentialAtBoot(read: CenterCredentialRead): CenterCredentialBootVerdict;
 /** 需要作用域 worker 的拉取令牌(`wpt_<self>`)却没配 `SEMA_REGISTRY_WORKER` ⇒ 中心对 per-principal caps
  *  逐次 403(caps fail-closed 拒全部 workflow)。boot 期一次性诊断用;判据只读本模块的种类判别。 */
 export declare function scopedTokenNeedsWorker(read: CenterCredentialRead, worker: string | undefined): boolean;
@@ -90,7 +143,8 @@ export declare function scopedTokenNeedsWorker(read: CenterCredentialRead, worke
  * 目录定的姿势,本批推广到 LKG)。
  */
 export declare function centerStateBin(worker: string | undefined, identity: string): string;
-/** 此刻凭证的身份(每次现读);文件形此刻不可读 ⇒ `undefined`(身份未知)。「我现在是谁」只有这一只读法。 */
+/** 此刻凭证的身份(每次现读);取不到凭证 ⇒ `undefined`(身份未知)—— 唯一例外是 `expired`:令牌不许出站,但信封还读得出
+ *  是谁(S-698:过期不等于换了人,盘上 LKG / prompt 分箱照常对得上)。「我现在是谁」只有这一只读法。 */
 export declare function credentialIdentityNow(source: CenterCredentialSource): string | undefined;
 /**
  * [ref] E-15 ② —— 一次中心往返的答复**仍属于此刻的凭证**:发出它所用的身份 = 此刻的身份。