zy-web-gate 1.0.0 → 1.1.0

package/README.md

@@ -31,6 +31,8 @@
 npm install zy-web-gate
 ```
 
+自 `1.1.0` 起自带 TypeScript 类型声明（`dist/index.d.ts`），TS 项目无需手写 `.d.ts`。
+
 ## 使用
 
 在**挂载真实应用之前**调用 `ensureGate()`。它只在「已通过门禁」时 resolve，所以未通过时真实应用绝不会挂载（无内容闪现）。

package/dist/cookie.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 由当前 host 推断可用于跨子域共享的父域。
+ *
+ * 例如当前在 a.example.com，应返回 example.com，
+ * 这样写入的 cookie 能被 my./b./x. 等所有兄弟子域读到。
+ *
+ * 注意：eu.org 在 Public Suffix List 上，浏览器禁止把 cookie 设到 eu.org，
+ * 所以父域只能取到 example.com 这一层，刚好是我们要的、也是安全的。
+ *
+ * 这里采用「去掉最左一段」的朴素策略：a.example.com -> example.com。
+ * 大多数「单层子域」场景够用；若有多级子域或想显式指定，用 options.cookieDomain 覆盖。
+ *
+ * @param {string} [hostname] 默认取 location.hostname
+ * @returns {string} 用于 cookie Domain 的父域；localhost / IP 等场景返回空串（表示按当前 host）
+ */
+export function inferParentDomain(hostname?: string): string;
+/**
+ * 读取指定名称的 cookie 值。
+ * @param {string} name
+ * @returns {string|null}
+ */
+export function readCookie(name: string): string | null;
+/**
+ * 写入跨子域 cookie。
+ *
+ * @param {string} name
+ * @param {string} value
+ * @param {object} opts
+ * @param {string} opts.domain  cookie 的 Domain，传空串则不写 Domain（仅当前 host）
+ * @param {number} opts.maxAgeSeconds  有效期（秒）
+ * @param {string} [opts.sameSite="Lax"]
+ * @param {boolean} [opts.secure=true]  HTTPS 下应为 true；本地 http 调试时会自动放宽
+ * @param {string} [opts.path="/"]
+ */
+export function writeCookie(name: string, value: string, opts: {
+    domain: string;
+    maxAgeSeconds: number;
+    sameSite?: string | undefined;
+    secure?: boolean | undefined;
+    path?: string | undefined;
+}): void;
+/**
+ * 删除跨子域 cookie（用于「登出」）。Domain / Path 必须和写入时一致才能删掉。
+ * @param {string} name
+ * @param {object} opts
+ * @param {string} opts.domain
+ * @param {string} [opts.path="/"]
+ */
+export function deleteCookie(name: string, opts: {
+    domain: string;
+    path?: string | undefined;
+}): void;

package/dist/index.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 访问门主入口。
+ *
+ * 行为：
+ *   1. 若父域 cookie 已存在有效登录态 -> 直接 resolve（放行，无 UI）。
+ *   2. 否则弹出密码页，等用户输入并通过接口校验。
+ *   3. 校验通过 -> 写父域 cookie -> resolve。
+ *
+ * 该 Promise 只在「已通过门禁」时 resolve；密码未通过时不会 resolve，
+ * 因此把它放在 createApp().mount() 之前 await，可保证未通过时真实应用绝不挂载。
+ *
+ * @param {GateOptions} [options]
+ * @returns {Promise<void>}
+ */
+export function ensureGate(options?: GateOptions): Promise<void>;
+/**
+ * 主动登出：清除父域 cookie。调用后下次进入任一子站会重新要求输入密码。
+ * @param {GateOptions} options 至少需与 ensureGate 一致的 cookieName / cookieDomain
+ */
+export function logoutGate(options?: GateOptions): void;
+export type GateOptions = {
+    /**
+     * 登录态 cookie 名，默认 "zy_web_gate"
+     */
+    cookieName?: string | undefined;
+    /**
+     * 写入的 cookie 值，默认 "1"
+     */
+    cookieValue?: string | undefined;
+    /**
+     * 显式指定父域；不传则自动推断（如 example.com）
+     */
+    cookieDomain?: string | undefined;
+    /**
+     * 登录态有效天数，默认 7
+     */
+    maxAgeDays?: number | undefined;
+    /**
+     * cookie SameSite，默认 "Lax"
+     */
+    sameSite?: string | undefined;
+    /**
+     * cookie Secure；不传则按当前协议自动判断
+     */
+    secure?: boolean | undefined;
+    /**
+     * 密码页标题
+     */
+    title?: string | undefined;
+    /**
+     * 密码页副标题
+     */
+    subtitle?: string | undefined;
+    /**
+     * 输入框占位文案
+     */
+    placeholder?: string | undefined;
+    /**
+     * 按钮文案
+     */
+    buttonText?: string | undefined;
+    /**
+     * 接口超时毫秒，默认 10000
+     */
+    timeoutMs?: number | undefined;
+};
+export { inferParentDomain, readCookie } from "./cookie.js";

package/dist/ui.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 创建并挂载密码页。返回一个对象，可用于销毁。
+ *
+ * @param {object} cfg
+ * @param {string} cfg.title
+ * @param {string} cfg.subtitle
+ * @param {string} cfg.placeholder
+ * @param {string} cfg.buttonText
+ * @param {(password: string) => Promise<{ok: boolean, message?: string}>} cfg.onSubmit
+ *        提交回调；返回 ok=true 时 UI 自动销毁，false 时显示 message。
+ * @returns {{ destroy: () => void }}
+ */
+export function mountPasswordGate(cfg: {
+    title: string;
+    subtitle: string;
+    placeholder: string;
+    buttonText: string;
+    onSubmit: (password: string) => Promise<{
+        ok: boolean;
+        message?: string;
+    }>;
+}): {
+    destroy: () => void;
+};

package/dist/verify.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 校验结果。
+ * @typedef {object} VerifyResult
+ * @property {boolean} ok      密码是否正确
+ * @property {boolean} [networkError]  是否因网络/接口异常导致（区别于「密码错」）
+ * @property {string}  [message]       可展示给用户的提示
+ */
+/**
+ * 调用校验接口。
+ *
+ * 接口约定：
+ *   请求  POST apiUrl  body: {"password": "用户输入"}
+ *   通过  HTTP 200, {"code":200, "data":{"match":true}}
+ *   密码错 HTTP 401, {"code":401, "data":{}}（或任何 match !== true 的响应）
+ *
+ * 判定规则：只有「HTTP ok 且 data.match === true」才算密码正确；
+ * 其余一律当密码错。网络层异常单独标记为 networkError，便于 UI 区分提示。
+ *
+ * @param {string} apiUrl
+ * @param {string} password
+ * @param {object} [opts]
+ * @param {number} [opts.timeoutMs=10000]
+ * @returns {Promise<VerifyResult>}
+ */
+export function verifyPassword(apiUrl: string, password: string, opts?: {
+    timeoutMs?: number | undefined;
+}): Promise<VerifyResult>;
+/**
+ * 校验结果。
+ */
+export type VerifyResult = {
+    /**
+     * 密码是否正确
+     */
+    ok: boolean;
+    /**
+     * 是否因网络/接口异常导致（区别于「密码错」）
+     */
+    networkError?: boolean | undefined;
+    /**
+     * 可展示给用户的提示
+     */
+    message?: string | undefined;
+};

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "zy-web-gate",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Framework-agnostic, pure-frontend shared-password page gate with cross-subdomain login state via a parent-domain cookie. No backend auth, no accounts — verification is delegated to a check-password API.",
   "type": "module",
   "main": "./dist/zy-web-gate.umd.cjs",
   "module": "./dist/zy-web-gate.js",
+  "types": "./dist/index.d.ts",
   "unpkg": "./dist/zy-web-gate.umd.cjs",
   "jsdelivr": "./dist/zy-web-gate.umd.cjs",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/zy-web-gate.js",
       "require": "./dist/zy-web-gate.umd.cjs"
     }
@@ -19,7 +21,8 @@
   ],
   "scripts": {
     "check": "node --check src/index.js && node --check src/cookie.js && node --check src/verify.js && node --check src/ui.js",
-    "build": "vite build",
+    "build": "vite build && npm run build:types",
+    "build:types": "tsc -p tsconfig.json",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -37,6 +40,7 @@
   "license": "ISC",
   "sideEffects": false,
   "devDependencies": {
+    "typescript": "^6.0.3",
     "vite": "^8.0.16"
   }
 }