hiwork-core 0.0.2 → 0.0.6

package/lib/client-policy.js

@@ -0,0 +1,82 @@
+/**
+ * 客户端版本策略（spec §6）：`GET /api/client/policy` 的免登录只读拉取。
+ *
+ * 网关返回的是**最终判定**（`loginMode` 等），插件只做投影不做策略逻辑，因此管理端
+ * 调整 `client.login_mode` 后重启插件即生效，无需发版（spec §6.1）。
+ *
+ * 本模块只负责「拉 + 严格解析」，投影与 fail-open 缺省由 `src/index.ts` 的
+ * `projectLoginMode` 完成：**非 200 / 非 JSON / 枚举非法 / 超时 / 网络异常一律返回
+ * undefined**，调用方据此回退 `DEFAULT_LOGIN_MODE`，绝不把用户锁在门外（spec §5.4 / §6.4）。
+ */
+import { PKG_VERSION } from "./version.js";
+/** fail-open 缺省值：策略缺失 / 失败 / 非法时一律按此投影（spec §5.4）。 */
+export const DEFAULT_LOGIN_MODE = 'both';
+/** 策略端点：域名一律来自 baseURL，不硬编码。 */
+export const CLIENT_POLICY_PATH = '/api/client/policy';
+/** 策略拉取默认超时：免登录只读接口，超过 5s 视同不可达（fail-open）。 */
+export const CLIENT_POLICY_TIMEOUT_MS = 5_000;
+/**
+ * 拼策略 URL：`{baseURL}/api/client/policy?platform=&arch=&version=&device_id=`。
+ * 参数固定顺序、逐个 `encodeURIComponent`（device_id 可能是任意 ASCII，含 `+/=` 也必须安全）；
+ * 空值参数直接省略（不产生 `version=` 这样的空参数）；baseURL 尾斜杠归一。
+ * @returns 完整 URL；缺 baseURL 时 undefined（调用方据此跳过请求）。
+ */
+export function buildClientPolicyURL(opts) {
+    const baseURL = typeof opts.baseURL === 'string' ? opts.baseURL.trim().replace(/\/+$/, '') : '';
+    if (baseURL === '')
+        return undefined;
+    const params = [
+        ['platform', opts.platform],
+        ['arch', opts.arch],
+        ['version', opts.version],
+        ['device_id', opts.deviceId],
+    ];
+    const query = params
+        .filter(([, value]) => typeof value === 'string' && value !== '')
+        .map(([key, value]) => `${key}=${encodeURIComponent(value)}`)
+        .join('&');
+    return query === '' ? `${baseURL}${CLIENT_POLICY_PATH}` : `${baseURL}${CLIENT_POLICY_PATH}?${query}`;
+}
+/**
+ * 严格解析响应体：只认 `loginMode` 恰好是三个枚举值之一的对象；
+ * 其余（非对象 / 字段缺失 / 非字符串 / 非法枚举值）一律 undefined。
+ */
+function parseLoginMode(payload) {
+    if (typeof payload !== 'object' || payload === null)
+        return undefined;
+    const value = payload.loginMode;
+    return value === 'browser' || value === 'form' || value === 'both' ? value : undefined;
+}
+/**
+ * 拉取并解析客户端策略。**永不抛异常**：任何失败都返回 undefined（fail-open）。
+ *
+ * 不记录响应原文——策略接口当前无敏感字段，但保持与其他网关调用一致的日志纪律。
+ */
+export async function fetchClientPolicy(opts) {
+    const url = buildClientPolicyURL(opts);
+    if (url === undefined)
+        return undefined;
+    try {
+        const res = await fetch(url, {
+            method: 'GET',
+            headers: { 'user-agent': `hiwork-core/${PKG_VERSION}`, accept: 'application/json' },
+            signal: AbortSignal.timeout(opts.timeoutMs ?? CLIENT_POLICY_TIMEOUT_MS),
+        });
+        // 严格 200：304 / 204 等一律视为不可用（本插件不维护 ETag 缓存，宁可按缺省放行）。
+        if (res.status !== 200)
+            return undefined;
+        let payload;
+        try {
+            payload = await res.json();
+        }
+        catch {
+            return undefined;
+        }
+        const loginMode = parseLoginMode(payload);
+        return loginMode === undefined ? undefined : { loginMode };
+    }
+    catch {
+        // 网络异常 / 超时（AbortSignal.timeout 抛 TimeoutError）/ 非法 URL：一律 fail-open。
+        return undefined;
+    }
+}