@pactor-app/permission 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pactor Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# @pactor-app/permission
+
+[Pactor](https://github.com/426-330/pactor) 的权限模块：权限码集合存储（PermissionStore）、适配 @pactor-app/runtime 的权限适配器、Menu / Page 守卫纯函数与表达式函数 `permission(code)`。
+
+浏览器只持有 Permission Set，DSL 中不出现 Role；前端权限只控制 UI（隐藏 / 禁用 / 拦截），后端必须再次鉴权。
+
+## 安装
+
+```bash
+npm install @pactor-app/permission
+# 或
+pnpm add @pactor-app/permission
+```
+
+零运行时依赖（仅 @pactor-app/core 类型），不依赖 React 与 @pactor-app/runtime，可纯 Node 使用与测试。
+
+## 示例
+
+```ts
+import {
+  PermissionStore,
+  createPermissionAdapter,
+  createPermissionFunction,
+  filterMenusByPermission,
+  checkPagePermission,
+} from '@pactor-app/permission';
+
+// bootstrap 阶段一次性注入权限码集合
+const store = new PermissionStore();
+store.setPermissions(['customer:view', 'customer:edit']);
+
+// 1. 注入 @pactor-app/runtime（结构化兼容 PermissionAdapter）
+const runtime = createPageRuntime(pageDsl, {
+  permission: createPermissionAdapter(store),
+});
+// - 节点 permission: 'customer:edit' 无权限时默认隐藏；
+// - permission: { code: 'customer:edit', denied: 'disabled' } 时注入 disabled: true；
+// - 动作配置无权限的 permission 时被 Action 引擎拦截（{ ok: false }）。
+
+// 2. Menu / Page 守卫（纯函数）
+const menus = filterMenusByPermission(rawMenus, store);
+const canEnter = checkPagePermission(pageMeta, store);
+
+// 3. 表达式函数（注入求值 options.functions 或作用域）
+const functions = { permission: createPermissionFunction(store) };
+// 支持 `${!permission('customer:edit')}` 形式
+
+// 4. 权限变更通知
+const off = store.subscribe(() => {/* 重新过滤菜单等 */});
+```
+
+## 功能一览
+
+- **PermissionStore**：`setPermissions(codes)`（整体替换）/ `clear()` / `has(code)` / `hasAny(codes)` / `hasAll(codes)` / `subscribe(listener)`（返回退订函数）。V1 精确匹配，不做通配符。
+- **`createPermissionAdapter(store)`**：结构化兼容 @pactor-app/runtime 的 `PermissionAdapter`，`check` 支持 string / string[]（hasAny）/ `{ code, denied }` 三种配置形态（对象形式只判定 `code`）。
+- **`resolvePermissionCheck(config, checker)`**：三种形态归一为 `{ allowed, denied }`（denied 缺省 `'hidden'`，未配置 permission 视为放行），Renderer 与 Guards 复用同一逻辑。
+- **`filterMenusByPermission(menus, checker)`**：递归移除无权限菜单项与空目录，不修改原数组，泛型保持菜单项类型。
+- **`checkPagePermission(page, checker)`**：页面无 permission 字段时放行。
+- **`createPermissionFunction(store)`**：返回 `(code: string) => boolean`，作为白名单函数注入表达式求值。
+
+## 文档
+
+完整文档见 <https://github.com/426-330/pactor/tree/main/docs>（`pnpm docs:dev` 本地启动文档站）。
+
+## License
+
+[MIT](../../LICENSE)

package/dist/index.cjs

@@ -0,0 +1,138 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  PermissionStore: () => PermissionStore,
+  checkPagePermission: () => checkPagePermission,
+  createPermissionAdapter: () => createPermissionAdapter,
+  createPermissionFunction: () => createPermissionFunction,
+  filterMenusByPermission: () => filterMenusByPermission,
+  resolvePermissionCheck: () => resolvePermissionCheck,
+  resolvePermissionCodes: () => resolvePermissionCodes
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/store.ts
+var PermissionStore = class {
+  constructor() {
+    this.codes = /* @__PURE__ */ new Set();
+    this.listeners = /* @__PURE__ */ new Set();
+  }
+  /** 整体替换权限码集合并通知订阅者 */
+  setPermissions(codes) {
+    this.codes = new Set(codes);
+    this.notify();
+  }
+  /** 清空权限码并通知订阅者 */
+  clear() {
+    this.codes.clear();
+    this.notify();
+  }
+  /** 是否持有某权限码；未设置（含空集合）一律返回 false */
+  has(code) {
+    return this.codes.has(code);
+  }
+  /** 任一命中即返回 true（组件 / 动作配置数组的语义） */
+  hasAny(codes) {
+    return codes.some((code) => this.codes.has(code));
+  }
+  /** 全部命中才返回 true */
+  hasAll(codes) {
+    return codes.every((code) => this.codes.has(code));
+  }
+  /** 订阅权限变更，返回退订函数 */
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  notify() {
+    for (const listener of [...this.listeners]) {
+      listener();
+    }
+  }
+};
+
+// src/resolve.ts
+function resolvePermissionCodes(config) {
+  if (typeof config === "string") {
+    return [config];
+  }
+  if (Array.isArray(config)) {
+    return config;
+  }
+  return Array.isArray(config.code) ? config.code : [config.code];
+}
+function resolvePermissionCheck(config, checker) {
+  if (config === void 0) {
+    return { allowed: true, denied: "hidden" };
+  }
+  const denied = typeof config === "object" && !Array.isArray(config) ? config.denied ?? "hidden" : "hidden";
+  return { allowed: checker.hasAny(resolvePermissionCodes(config)), denied };
+}
+
+// src/adapter.ts
+function createPermissionAdapter(store) {
+  return {
+    check(permission) {
+      return resolvePermissionCheck(permission, store).allowed;
+    }
+  };
+}
+
+// src/guards.ts
+function filterMenusByPermission(menus, checker) {
+  const result = [];
+  for (const menu of menus) {
+    if (!resolvePermissionCheck(menu.permission, checker).allowed) {
+      continue;
+    }
+    if (menu.children === void 0) {
+      result.push(menu);
+      continue;
+    }
+    const children = filterMenusByPermission(menu.children, checker);
+    if (menu.children.length > 0 && children.length === 0) {
+      continue;
+    }
+    result.push({ ...menu, children });
+  }
+  return result;
+}
+function checkPagePermission(page, checker) {
+  return resolvePermissionCheck(page.permission, checker).allowed;
+}
+
+// src/expression.ts
+function createPermissionFunction(store) {
+  return (code) => store.has(code);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PermissionStore,
+  checkPagePermission,
+  createPermissionAdapter,
+  createPermissionFunction,
+  filterMenusByPermission,
+  resolvePermissionCheck,
+  resolvePermissionCodes
+});

package/dist/index.d.cts

@@ -0,0 +1,112 @@
+import { PermissionDeniedStrategy, PermissionConfig } from '@pactor-app/core';
+
+/** 权限变更监听器 */
+type PermissionListener = () => void;
+/**
+ * PermissionStore（设计文档第 43 节，决策 D1）：
+ * 浏览器端只持有权限码集合（Permission Set），DSL 中不出现 Role。
+ *
+ * 内部为 `Set<string>`；`setPermissions` 整体替换（bootstrap 阶段一次性
+ * 注入），`clear` 清空；两者都会通知订阅者。精确匹配，不做通配符。
+ */
+declare class PermissionStore {
+    private codes;
+    private listeners;
+    /** 整体替换权限码集合并通知订阅者 */
+    setPermissions(codes: string[]): void;
+    /** 清空权限码并通知订阅者 */
+    clear(): void;
+    /** 是否持有某权限码；未设置（含空集合）一律返回 false */
+    has(code: string): boolean;
+    /** 任一命中即返回 true（组件 / 动作配置数组的语义） */
+    hasAny(codes: string[]): boolean;
+    /** 全部命中才返回 true */
+    hasAll(codes: string[]): boolean;
+    /** 订阅权限变更，返回退订函数 */
+    subscribe(listener: PermissionListener): () => void;
+    private notify;
+}
+
+/**
+ * 结构化权限判定接口（决策 D3）：只需 `hasAny`。
+ * PermissionStore 天然满足该接口；runtime 的 PermissionAdapter
+ * 也可经简单包装适配。避免 permission → runtime 的依赖。
+ */
+interface PermissionChecker {
+    hasAny(codes: string[]): boolean;
+}
+/** 权限解析结果：是否放行 + 无权限时的处理策略 */
+interface ResolvedPermission {
+    allowed: boolean;
+    denied: PermissionDeniedStrategy;
+}
+/** 提取权限码数组：string / string[] / `{ code }` 三种形态归一 */
+declare function resolvePermissionCodes(config: PermissionConfig): string[];
+/**
+ * 权限配置统一解析（决策 D3）：
+ * string / string[] / `{ code, denied }` 三种形态归一为
+ * `{ allowed, denied }`；数组按 hasAny；denied 缺省 `'hidden'`；
+ * 未配置 permission（undefined）视为放行。
+ *
+ * Renderer 与 Menu / Page Guard 复用同一逻辑，避免各处重复解释配置形状。
+ */
+declare function resolvePermissionCheck(config: PermissionConfig | undefined, checker: PermissionChecker): ResolvedPermission;
+
+/**
+ * 创建适配 @pactor-app/runtime `PermissionAdapter` 的权限适配器（决策 D4）。
+ *
+ * 返回对象结构化兼容 runtime 的 `PermissionAdapter` 接口
+ * （`check(permission: PermissionConfig): boolean`），但不 import
+ * @pactor-app/runtime 的任何运行时值，本包保持零 React / 零 runtime 依赖。
+ * 类型兼容性由测试中的编译期断言锁定（devDependency 仅用于类型）。
+ *
+ * 三种配置形态均只判定"有没有权限"：对象形式只检查 `code`，
+ * denied 策略由 Renderer / Guard 解释。
+ */
+declare function createPermissionAdapter(store: PermissionStore): {
+    check(permission: PermissionConfig): boolean;
+};
+
+/**
+ * 菜单项结构约束：带可选 permission 与递归 children。
+ * 泛型保持调用方的菜单项类型（额外字段原样保留）。
+ */
+type MenuItemWithPermission<T> = T & {
+    permission?: PermissionConfig;
+    children?: MenuItemWithPermission<T>[];
+};
+/**
+ * Menu Guard（决策 D5）：递归过滤无权限的菜单项。
+ *
+ * - 未配置 permission 的项保留；
+ * - children 被全部移除的空目录一并移除；
+ * - 返回新数组，原数组与原菜单项对象不被修改
+ *   （children 被过滤的项返回浅拷贝）。
+ *
+ * checker 为结构化接口，直接传 PermissionStore 即可。
+ */
+declare function filterMenusByPermission<T extends {
+    permission?: PermissionConfig;
+    children?: T[];
+}>(menus: readonly T[], checker: PermissionChecker): T[];
+/**
+ * Page Guard（决策 D5）：页面元信息含 permission 时判定是否放行；
+ * 无 permission 字段一律放行。checker 为结构化接口，直接传
+ * PermissionStore 即可。
+ */
+declare function checkPagePermission<T extends {
+    permission?: PermissionConfig;
+}>(page: T, checker: PermissionChecker): boolean;
+
+/**
+ * 表达式函数 `permission(code)` 工厂（决策 D6）：
+ * 返回 `(code: string) => boolean`，可作为白名单函数注入
+ * @pactor-app/expression 求值（`options.functions`）或求值作用域，
+ * 支持 `${!permission('customer:edit')}` 形式。
+ *
+ * PageRuntime 的自动注入由上层组合层（@pactor-app/app）决定，本包不改变
+ * PageRuntime 的既有行为。
+ */
+declare function createPermissionFunction(store: PermissionStore): (code: string) => boolean;
+
+export { type MenuItemWithPermission, type PermissionChecker, type PermissionListener, PermissionStore, type ResolvedPermission, checkPagePermission, createPermissionAdapter, createPermissionFunction, filterMenusByPermission, resolvePermissionCheck, resolvePermissionCodes };

package/dist/index.d.ts

@@ -0,0 +1,112 @@
+import { PermissionDeniedStrategy, PermissionConfig } from '@pactor-app/core';
+
+/** 权限变更监听器 */
+type PermissionListener = () => void;
+/**
+ * PermissionStore（设计文档第 43 节，决策 D1）：
+ * 浏览器端只持有权限码集合（Permission Set），DSL 中不出现 Role。
+ *
+ * 内部为 `Set<string>`；`setPermissions` 整体替换（bootstrap 阶段一次性
+ * 注入），`clear` 清空；两者都会通知订阅者。精确匹配，不做通配符。
+ */
+declare class PermissionStore {
+    private codes;
+    private listeners;
+    /** 整体替换权限码集合并通知订阅者 */
+    setPermissions(codes: string[]): void;
+    /** 清空权限码并通知订阅者 */
+    clear(): void;
+    /** 是否持有某权限码；未设置（含空集合）一律返回 false */
+    has(code: string): boolean;
+    /** 任一命中即返回 true（组件 / 动作配置数组的语义） */
+    hasAny(codes: string[]): boolean;
+    /** 全部命中才返回 true */
+    hasAll(codes: string[]): boolean;
+    /** 订阅权限变更，返回退订函数 */
+    subscribe(listener: PermissionListener): () => void;
+    private notify;
+}
+
+/**
+ * 结构化权限判定接口（决策 D3）：只需 `hasAny`。
+ * PermissionStore 天然满足该接口；runtime 的 PermissionAdapter
+ * 也可经简单包装适配。避免 permission → runtime 的依赖。
+ */
+interface PermissionChecker {
+    hasAny(codes: string[]): boolean;
+}
+/** 权限解析结果：是否放行 + 无权限时的处理策略 */
+interface ResolvedPermission {
+    allowed: boolean;
+    denied: PermissionDeniedStrategy;
+}
+/** 提取权限码数组：string / string[] / `{ code }` 三种形态归一 */
+declare function resolvePermissionCodes(config: PermissionConfig): string[];
+/**
+ * 权限配置统一解析（决策 D3）：
+ * string / string[] / `{ code, denied }` 三种形态归一为
+ * `{ allowed, denied }`；数组按 hasAny；denied 缺省 `'hidden'`；
+ * 未配置 permission（undefined）视为放行。
+ *
+ * Renderer 与 Menu / Page Guard 复用同一逻辑，避免各处重复解释配置形状。
+ */
+declare function resolvePermissionCheck(config: PermissionConfig | undefined, checker: PermissionChecker): ResolvedPermission;
+
+/**
+ * 创建适配 @pactor-app/runtime `PermissionAdapter` 的权限适配器（决策 D4）。
+ *
+ * 返回对象结构化兼容 runtime 的 `PermissionAdapter` 接口
+ * （`check(permission: PermissionConfig): boolean`），但不 import
+ * @pactor-app/runtime 的任何运行时值，本包保持零 React / 零 runtime 依赖。
+ * 类型兼容性由测试中的编译期断言锁定（devDependency 仅用于类型）。
+ *
+ * 三种配置形态均只判定"有没有权限"：对象形式只检查 `code`，
+ * denied 策略由 Renderer / Guard 解释。
+ */
+declare function createPermissionAdapter(store: PermissionStore): {
+    check(permission: PermissionConfig): boolean;
+};
+
+/**
+ * 菜单项结构约束：带可选 permission 与递归 children。
+ * 泛型保持调用方的菜单项类型（额外字段原样保留）。
+ */
+type MenuItemWithPermission<T> = T & {
+    permission?: PermissionConfig;
+    children?: MenuItemWithPermission<T>[];
+};
+/**
+ * Menu Guard（决策 D5）：递归过滤无权限的菜单项。
+ *
+ * - 未配置 permission 的项保留；
+ * - children 被全部移除的空目录一并移除；
+ * - 返回新数组，原数组与原菜单项对象不被修改
+ *   （children 被过滤的项返回浅拷贝）。
+ *
+ * checker 为结构化接口，直接传 PermissionStore 即可。
+ */
+declare function filterMenusByPermission<T extends {
+    permission?: PermissionConfig;
+    children?: T[];
+}>(menus: readonly T[], checker: PermissionChecker): T[];
+/**
+ * Page Guard（决策 D5）：页面元信息含 permission 时判定是否放行；
+ * 无 permission 字段一律放行。checker 为结构化接口，直接传
+ * PermissionStore 即可。
+ */
+declare function checkPagePermission<T extends {
+    permission?: PermissionConfig;
+}>(page: T, checker: PermissionChecker): boolean;
+
+/**
+ * 表达式函数 `permission(code)` 工厂（决策 D6）：
+ * 返回 `(code: string) => boolean`，可作为白名单函数注入
+ * @pactor-app/expression 求值（`options.functions`）或求值作用域，
+ * 支持 `${!permission('customer:edit')}` 形式。
+ *
+ * PageRuntime 的自动注入由上层组合层（@pactor-app/app）决定，本包不改变
+ * PageRuntime 的既有行为。
+ */
+declare function createPermissionFunction(store: PermissionStore): (code: string) => boolean;
+
+export { type MenuItemWithPermission, type PermissionChecker, type PermissionListener, PermissionStore, type ResolvedPermission, checkPagePermission, createPermissionAdapter, createPermissionFunction, filterMenusByPermission, resolvePermissionCheck, resolvePermissionCodes };

package/dist/index.js

@@ -0,0 +1,105 @@
+// src/store.ts
+var PermissionStore = class {
+  constructor() {
+    this.codes = /* @__PURE__ */ new Set();
+    this.listeners = /* @__PURE__ */ new Set();
+  }
+  /** 整体替换权限码集合并通知订阅者 */
+  setPermissions(codes) {
+    this.codes = new Set(codes);
+    this.notify();
+  }
+  /** 清空权限码并通知订阅者 */
+  clear() {
+    this.codes.clear();
+    this.notify();
+  }
+  /** 是否持有某权限码；未设置（含空集合）一律返回 false */
+  has(code) {
+    return this.codes.has(code);
+  }
+  /** 任一命中即返回 true（组件 / 动作配置数组的语义） */
+  hasAny(codes) {
+    return codes.some((code) => this.codes.has(code));
+  }
+  /** 全部命中才返回 true */
+  hasAll(codes) {
+    return codes.every((code) => this.codes.has(code));
+  }
+  /** 订阅权限变更，返回退订函数 */
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  notify() {
+    for (const listener of [...this.listeners]) {
+      listener();
+    }
+  }
+};
+
+// src/resolve.ts
+function resolvePermissionCodes(config) {
+  if (typeof config === "string") {
+    return [config];
+  }
+  if (Array.isArray(config)) {
+    return config;
+  }
+  return Array.isArray(config.code) ? config.code : [config.code];
+}
+function resolvePermissionCheck(config, checker) {
+  if (config === void 0) {
+    return { allowed: true, denied: "hidden" };
+  }
+  const denied = typeof config === "object" && !Array.isArray(config) ? config.denied ?? "hidden" : "hidden";
+  return { allowed: checker.hasAny(resolvePermissionCodes(config)), denied };
+}
+
+// src/adapter.ts
+function createPermissionAdapter(store) {
+  return {
+    check(permission) {
+      return resolvePermissionCheck(permission, store).allowed;
+    }
+  };
+}
+
+// src/guards.ts
+function filterMenusByPermission(menus, checker) {
+  const result = [];
+  for (const menu of menus) {
+    if (!resolvePermissionCheck(menu.permission, checker).allowed) {
+      continue;
+    }
+    if (menu.children === void 0) {
+      result.push(menu);
+      continue;
+    }
+    const children = filterMenusByPermission(menu.children, checker);
+    if (menu.children.length > 0 && children.length === 0) {
+      continue;
+    }
+    result.push({ ...menu, children });
+  }
+  return result;
+}
+function checkPagePermission(page, checker) {
+  return resolvePermissionCheck(page.permission, checker).allowed;
+}
+
+// src/expression.ts
+function createPermissionFunction(store) {
+  return (code) => store.has(code);
+}
+export {
+  PermissionStore,
+  checkPagePermission,
+  createPermissionAdapter,
+  createPermissionFunction,
+  filterMenusByPermission,
+  resolvePermissionCheck,
+  resolvePermissionCodes
+};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@pactor-app/permission",
+  "version": "0.1.0",
+  "description": "Pactor permission: permission code store, runtime permission adapter, menu/page guards and expression function",
+  "keywords": [
+    "pactor",
+    "dsl",
+    "server-driven-ui",
+    "permission",
+    "access-control"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/426-330/pactor.git",
+    "directory": "packages/permission"
+  },
+  "homepage": "https://github.com/426-330/pactor/tree/main/packages/permission",
+  "bugs": "https://github.com/426-330/pactor/issues",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@pactor-app/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.18",
+    "react": "^19.2.8",
+    "@pactor-app/runtime": "0.1.0",
+    "@pactor-app/expression": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}