w-web-perm 1.1.13 → 1.1.15

package/server/WWebPerm.mjs

@@ -21,38 +21,41 @@ import fsIsFolder from 'wsemi/src/fsIsFolder.mjs'
 import fsIsFile from 'wsemi/src/fsIsFile.mjs'
 import replace from 'wsemi/src/replace.mjs'
 import strdelleft from 'wsemi/src/strdelleft.mjs'
-import ltdtmapping from 'wsemi/src/ltdtmapping.mjs'
-import pmKeyMutex from 'wsemi/src/pmKeyMutex.mjs'
 import cacheSt from 'wsemi/src/cacheSt.mjs'
 import WServHapiServer from 'w-serv-hapi/src/WServHapiServer.mjs'
 import WServOrm from 'w-serv-orm/src/WServOrm.mjs'
 import checkOptRemoved from 'w-serv-orm/src/checkOptRemoved.mjs'
 import ds from '../src/schema/index.mjs'
 import { getUserRules } from '../src/plugins/mShare.mjs'
-import procCore, { toOutKey, isRowObj } from './procCore.mjs'
+import procCore, { toOutKey, pickClientOpt } from './procCore.mjs'
+import syncCore from './syncCore.mjs'
 import createLockSave from './lockSave.mjs'
 import procLang from './procLang.mjs'
 import srLogInit from './srLog.mjs'
 import procStaInfor from './procStaInfor.mjs'
 import { maskTok, maskQuery, maskUrl } from './maskLog.mjs'
 import wrapInjected from './wrapInjected.mjs'
-import validateRowsBeforeWrite from './validateRows.mjs'
-import planRefChanges, { REF_OF, diffRefTargets } from '../src/js/refCascade.mjs'
-import { findDupIndex, findKeyOtherFrom, withTabLocks, mapKeyOf, checkMapKeyBatch, pickUniqueUser } from './keyCheck.mjs'
-import { checkCascadePlan, writeWithCascade, buildSyncRowsNew } from './cascadeWrite.mjs'
+import { pickUniqueUser, findLoginUsers, mapKeyOf } from './keyCheck.mjs'
 import { createAuthorizeExec, wrapOperOrm } from './dataChannel.mjs'
-import { markHasKey, keepAssignOnMissing, keepAssignByEntity, countIdRenumber } from './syncKeep.mjs'
+import isAdminRow from './adminCheck.mjs'
 
 
 /**
  * 權限伺服器
  *
+ * 身分驗證責任(dspec/使用者身分驗證原則.md 第三節, 使用方套件標準註解): 框架(w-converhp、w-serv-hapi、w-serv-webdata、w-serv-orm)不驗證 token, 一律由本套件負責.
+ * 連線閘(verifyConn)與執行身分(getUserIdByToken)皆須完整驗證(token 有效、本系統使用者存在且啟用、部署方授權); hapi apis 路由各自驗證; 函數層級另檢查角色或成員; 公開入口只限列名者.
+ * 本套件之落實(perm-run01 起「權限後台與資料通道只限系統管理員」, 規則帳本 R-ADMIN-ONLY-01): 資料通道之連線閘(標頭 token, 所有入口: main 之 RPC／表 select／系統函數, 上傳下載各 apiType)與執行身分(請求本體 __sysToken__)、後台登入檢查(/api/getUserByToken)皆經 getAndVerifyAdminUser
+ * (外部 getUserByToken → perm users 存在且 isActive='y' → 部署方 verifyClientUser → perm users 表之列 isAdmin='y'; perm 以自身 users 表為權威, 不採 token 宣稱之 isAdmin), 任一關不過函數不執行(一般使用者即使部署方放行亦被拒, 回 userNotAdmin);
+ * 一般使用者(isAdmin='n')只能經 /api/getPerm 以 token 查本人權限樹; 改變狀態之 kpFunExt 函數(updateTargets／updatePemis／updateGrups／updateUsers)另保留 perm users 表中有效且 isAdmin='y' 之縱深檢查(requireAdmin), 不符回 userNotAdmin、零寫入;
+ * hapi apis 路由: getUserByToken(只限管理員)／getPerm(任何通過 verifyClientUser 之有效使用者, 回本人權限樹)驗 client 使用者, getPermUserInfor／syncAndReplaceTabs 驗 app 使用者(verifyAppUser); 無公開入口(前端靜態檔除外).
+ *
  * @class
  * @param {Function} WOrm 輸入資料庫ORM函數
  * @param {String} url 輸入資料庫連線字串，例如w-orm-lmdb為'./db'，或w-orm-mongodb為'mongodb://username:password@$127.0.0.1:27017'
  * @param {String} db 輸入資料庫名稱字串
  * @param {Function} getUserByToken 輸入處理函數，函數會傳入使用者token，通過此函數處理後並回傳使用者資訊物件，並至少須提供'id'、'email'、'name'、'isAdmin'欄位，且'isAdmin'限輸入'y'或'n'。注意: token 回傳之'isAdmin'僅供識別，權限系統一律以自身users表該使用者之'isAdmin'欄位值為權威，不會被 token 宣稱之值複寫。函數拋錯或reject時視同查無使用者(回自家錯誤key，錯誤原文不回前端、不入log，只於srLog記warn)
- * @param {Function} verifyClientUser 輸入驗證瀏覽使用者身份之處理函數，函數會傳入使用者資訊物件(perm users 表之列)與來源字串from，通過此函數識別後回傳布林值(可為Promise)，允許使用者回傳true，反之回傳false。from 值域: 'getUserByToken'(登入)、'getPerm'(api/getPerm)、以及資料通道之 apiType 'main'(RPC 與 ORM 執行)、'upload-controller'、'upload-slice'、'download-get-filename'、'download-get-file'、'download'；資料通道與登入採同一授權強度(反查 perm users 且 isActive='y' 後再經本函數)；函數拋錯或reject時視同回傳false
+ * @param {Function} verifyClientUser 輸入驗證瀏覽使用者身份之處理函數，函數會傳入使用者資訊物件(perm users 表之列)與來源字串from，通過此函數識別後回傳布林值(可為Promise)，允許使用者回傳true，反之回傳false。from 值域: 'getUserByToken'(登入)、'getPerm'(api/getPerm)、以及資料通道之 apiType 'main'(RPC 與 ORM 執行; 連線閘驗標頭 token、執行身分〔getUserIdByToken〕驗請求本體 __sysToken__, 兩者各經本函數一次, 本體 token 與標頭 token 不同時兩個使用者各自驗證)、'upload-controller'、'upload-slice'、'download-get-filename'、'download-get-file'、'download'；資料通道與登入採同一授權強度(反查 perm users 且 isActive='y' 後再經本函數)；函數拋錯或reject時視同回傳false。本函數收到的是該列之淺層副本，改寫其欄位不影響本套件後續採用之執行身分與角色判定。本函數通過後，本套件另要求資料通道與後台登入(from 為 'getUserByToken'、'main'、'upload-controller' 等)限 perm users 表中 isAdmin 為 'y' 者(一般使用者即使本函數放行亦被拒，回 userNotAdmin)，故本函數不必再以 from 區分管理員與一般使用者，但可再收緊；一般使用者查本人權限樹之 /api/getPerm(from 為 'getPerm')仍會呼叫本函數，勿回傳 user.isAdmin === 'y' 而擋掉他們
  * @param {Function} verifyAppUser 輸入驗證應用程序使用者身份之處理函數，函數會傳入使用者資訊物件，通過此函數識別後回傳布林值，允許使用者回傳true，反之回傳false；函數拋錯或reject時視同回傳false
  * @param {Object} [opt={}] 輸入設定物件，預設{}
  * @param {Integer} [opt.serverPort=11006] 輸入伺服器通訊port，預設11006。註：原opt.useCheckUser、opt.getUserById、opt.useExcludeWhenNotAdmin已隨w-serv-orm 1.1.9移除，給予undefined、null、false以外之值時建構即拋錯(錯誤訊息出自w-serv-orm之checkOptRemoved，並記srLog)；資料通道之使用者授權由verifyConn(verifyClientUser)負責、表操作只開放select，刪除該三鍵即可，無須替代設定
@@ -61,7 +64,7 @@ import { markHasKey, keepAssignOnMissing, keepAssignByEntity, countIdRenumber }
  * @param {String} [opt.webLogo=''] 輸入站台logo字串，採base64格式，預設''
  * @param {String} [opt.subfolder=''] 輸入站台所在子目錄字串，提供站台位於內網採反向代理進行服務時，故需支援位於子目錄情形，預設''
  * @param {String} [opt.urlRedirect=''] 輸入錯誤時自動轉址字串，提供站台例如無法登入或驗證失敗時須自動轉址，預設''
- * @param {String} [opt.mappingBy='id'] 輸入外部系統識別使用者token後所提供之資料物件，與權限系統之使用者資料物件，兩者間查找之對應欄位，可選'id'、'email'、'name'，未給或非此三者時為'id'，預設'id'。對應鍵須能唯一指出使用者：mappingBy為'email'或'name'時，外部同步(syncAndReplaceTabs)users之有效(isActive為'y')列，該欄位須為非空字串且與本批及其他from之有效列皆不重複(違規整批拒收invalidRows)；登入查找以對應鍵於權限系統users命中多於1筆有效使用者時一律拒絕(ambiguousUserFromPerm)，不取首筆；mappingBy為'id'(預設)時不另檢查
+ * @param {String} [opt.mappingBy='id'] 輸入外部系統識別使用者token後所提供之資料物件，與權限系統之使用者資料物件，兩者間查找之對應欄位，可選'id'、'email'、'name'，未給或非此三者時為'id'，預設'id'。對應鍵須能唯一指出使用者：mappingBy為'email'或'name'時，外部同步(syncAndReplaceTabs)users之有效(isActive為'y')列，該欄位須為非空字串且與本批及其他from之有效列皆不重複(違規整批拒收invalidRows)；登入查找以對應鍵於權限系統users命中多於1筆有效使用者時一律拒絕(ambiguousUserFromPerm)，不取首筆；mappingBy為'id'(預設)時，後台列(from為空)以其id對應外部token使用者之id，外部同步列(from非空)則以其來源鍵srcKey對應(外部列之id為本系統配發之內部主鍵，不是登入識別；升版前同步寫入、尚無srcKey之舊外部列在首次匯入補上srcKey前暫以id對應)，並防止撞值(登入識別值須跨全表唯一，不論isActive、含他來源外部列；不同外部系統之使用者id碰撞常見而非同一人，已停用者之token不得對到他來源之有效列)：外部同步(syncAndReplaceTabs)批次內任一列之srcKey等於他來源任一既有列之登入識別值(後台列id、他來源外部列srcKey)時整批拒收(loginIdCollision，零寫入，請部署方改用可唯一對應之鍵，如以email對應並將mappingBy設為'email')、後台存檔(updateUsers)新增或改變之後台列id撞到任一外部列srcKey時整次拒收(loginIdCollision，零變更)，登入時若命中多於1筆(不論有效與否)則拒絕(ambiguousUserFromPerm)、恰命中1筆但已停用視同查無(cannotGetUserFromPerm)；mappingBy為'id'時getPermUserInfor之userId亦依此對應解析(外部列傳其srcKey、後台列傳id，不是內部id；命中多筆拒絕ambiguousUserFromPerm)，'email'／'name'時userId仍為perm內部id；升版前既有之跨來源重複srcKey歷史資料不阻擋存檔，但登入一律拒絕，請依README Upgrade Notes盤點處置
  * @param {Boolean} [opt.cascadeRename=true] 輸入群組、權限改名時是否連帶更新引用它之授權字串(users.cgrups、grups.cpemis)，預設true。改名以主鍵id判定(同id異名)，後台整表儲存與外部同步(同一from內)皆適用，於同一次寫入內改寫並可能寫入外部來源之users列之cgrups；給false則不連帶(引用成為懸空，視同引用查無對象而收嚴並於頁面提示)。群組、權限、標的被刪除時之引用連帶清理(users.cgrups、grups.cpemis、pemis.crules)不受此設定影響
  * @param {String} [opt.lockExternalRows='y'] 輸入後台是否不得改外部列(from為非空字串，即經syncAndReplaceTabs由外部來源同步之列)，可選'y'或'n'，預設'y'。'y'時伺服端強制：後台新增列from須為空字串、外部列不可刪除、不可改from、身分/結構欄(指派欄與順序以外之欄位)不可改，違規整次拒收(saveFromNotAllowed／saveExternalRowChanged)；授權指派欄(users.cgrups、grups.cpemis、pemis.crules)後台可寫，但須附載入基準(用戶端自動附帶)，無基準者拒收(saveBaselineRequired)；外部列之order由外部擁有、後台儲存不重編。給'n'回到舊行為(僅保留from須為字串之檢查)。升版後既有庫中from為非空字串之列即視為外部列而唯讀，請先以g_fixFromType.mjs／g_purgeFrom.mjs盤點(見README Upgrade Notes)
  * @param {String} [opt.logFd='./logs'] 輸入log紀錄儲存位置字串，預設'./logs'
@@ -125,7 +128,9 @@ import { markHasKey, keepAssignOnMissing, keepAssignByEntity, countIdRenumber }
  *     console.log('verifyClientUser/user', user)
  *     // return false //測試無法登入
  *     console.log('於生產環境時得加入限制瀏覽器使用者身份機制')
- *     return user.isAdmin === 'y' //測試僅系統管理者使用
+ *     //本套件於此函數通過後，另要求資料通道與後台登入限系統管理員(perm users 表之 isAdmin 為 'y')，一般使用者仍可經 /api/getPerm(from 為 'getPerm')以 token 查本人權限樹，
+ *     //故此處不可回傳 user.isAdmin === 'y'(會擋掉一般使用者之 /api/getPerm); 僅需放行有效之瀏覽使用者，或依 from 與自家政策再收緊(例如依來源網段或系統別拒絕)
+ *     return true
  * }
  *
  * let verifyAppUser = (user, from) => {
@@ -318,34 +323,26 @@ function WWebPerm(WOrm, url, db, getUserByToken, verifyClientUser, verifyAppUser
     let { woItems, procOrm } = wp
 
 
-    //pmKeyMutex: per-key in-memory mutex, 同 key 序列化、不同 key 並行.
-    //perm 為「整表批次 diff」寫入, key 粒度為整表: tabWriteKey(keyTable)(= 'tabWrite:' + keyTable), 外部同步與後台整表寫入共用同鍵, 防同表並行 race (lost update) 與唯一性檢查被交錯略過 (R-WRITE-LOCK-01).
-    let kmx = pmKeyMutex()
+    //lockTabs, guardWrite: w-serv-orm 1.1.17 的每表一鍵表鎖與原子防護(多人同時編輯規格第 6、7 節; 規則帳本 R-LOCK-CORE-01), 取自 WServOrm 回傳物件——**唯一**的鎖管理器.
+    //perm 為「整表批次 diff」寫入, 鎖粒度為整表: 後台整表寫入(procCore.updateTabItems 之 guardWrite)、外部同步(syncAndReplaceTabs)與引用連帶之引用端寫入皆取同一把表鎖, 防同表並行 race (lost update) 與唯一性檢查被交錯略過 (R-WRITE-LOCK-01).
+    //不再自建 pmKeyMutex／鎖鍵(原 tabWriteKey 已移除); 鎖不可重入, 多表依階層巢狀取鎖見 keyCheck.withTabLocks(R-WRITE-LOCK-02)
+    let lockTabs = wp.withTabLocks
+    let guardWrite = wp.guardWrite
 
 
-    //syncWarns: 外部同步「同一 from 同名異 id」(疑似 id 重編)之提示登錄(記憶體, 重啟即清; 主控定案: 不加開關, 記 warn log 並使頁面可提示):
-    //以「表名＋來源」為鍵, 最近一次同步有此情形者登錄筆數與時間, 已無此情形者清除; 只含表名、來源名稱、筆數、時間, 不含個資
-    let kpSyncWarn = new Map()
-    let setSyncWarn = (keyTable, from, n) => {
-        let k = `${keyTable}\u0000${from}`
-        if (n > 0) {
-            kpSyncWarn.set(k, { keyTable, from, n, time: new Date().toISOString() })
-        }
-        else {
-            kpSyncWarn.delete(k)
-        }
-    }
-    let getSyncWarns = () => [...kpSyncWarn.values()]
+    //sc: 外部匯入(POST /syncAndReplaceTabs)核心(server/syncCore.mjs; perm-run03 起依來源鍵 srcKey 差異同步, R-IMPORT-01): 與後台整表寫入共用同一個鎖管理器(lockTabs).
+    //syncWarns(同一 from 同名異 srcKey 之疑似來源鍵重編提示)之登錄亦在其內(記憶體, 重啟即清; 不含個資, 僅表名、來源名稱、筆數、時間)
+    let sc = syncCore({ woItems, procOrm, lockTabs, srLog, mappingBy, cascadeRename })
 
 
     //lockSave: 後台整表寫入(updateTabItems)之雙擊防護(後端, 見 lockSave.mjs, ADR-025): 以「updateTabItems:{表名}:{操作者 id}」於 cacheSt 原子占位,
-    //同一操作者之同表寫入處理中再送出即 reject 'saveInProgress'(不排隊); 包在 kmx 之外層, 不同操作者之並行仍由 kmx 序列化(ADR-012)
+    //同一操作者之同表寫入處理中再送出即 reject 'saveInProgress'(不排隊); 包在表鎖之外層, 不同操作者之並行仍由表鎖序列化(ADR-012)
     let cst = cacheSt()
     let lockSave = createLockSave(cst)
 
 
     //procCore: 整表批次 diff 寫入邏輯 (updateTabItems + updateTargets/Pemis/Grups/Users)
-    let pc = procCore(woItems, procOrm, { srLog, kmx, lockSave, mappingBy, cascadeRename, lockExternalRows }) //mappingBy 供 users 整表寫入的對應鍵檢查(R-PRINCIPLE-00 適用表 h); cascadeRename 供群組／權限改名之引用級聯(適用表 m); lockExternalRows 供後台對外部列之守門(F-23)
+    let pc = procCore(woItems, procOrm, { srLog, withTabLocks: lockTabs, guardWrite, lockSave, mappingBy, cascadeRename, lockExternalRows }) //mappingBy 供 users 整表寫入的對應鍵檢查(R-PRINCIPLE-00 適用表 h); cascadeRename 供群組／權限改名之引用級聯(適用表 m); lockExternalRows 供後台對外部列之守門(F-23)
 
 
     //procStaInfor: 統計資訊, fdLog 對齊 srLog 使用同一目錄(讀 settings.logFd, fallback 邏輯同 srLog.mjs); mock 由 settings.staEventMock 注入(e2e 統計圖穩定用)
@@ -384,7 +381,7 @@ function WWebPerm(WOrm, url, db, getUserByToken, verifyClientUser, verifyAppUser
 
             cascadeRename, //改名是否連帶更新引用(opt.cascadeRename), 供清單頁儲存前預覽與伺服端一致(R-REF-CASCADE-01)
             lockExternalRows: lockExternalRows ? 'y' : 'n', //後台是否不得改外部列(opt.lockExternalRows), 供清單頁逐列唯讀、複製重置 from 與伺服端一致(R-EXT-OWN-01)
-            syncWarns: getSyncWarns(), //外部同步疑似 id 重編之提示(同一 from 同名異 id), 供清單頁橫幅(原則 3: 提示); 不含個資, 僅表名、來源名稱、筆數、時間
+            syncWarns: sc.getSyncWarns(), //外部同步疑似來源鍵重編之提示(同一 from 同名異 srcKey), 供清單頁橫幅(原則 3: 提示); 不含個資, 僅表名、來源名稱、筆數、時間
 
             widthTargetId,
             widthTargetDescription,
@@ -468,8 +465,8 @@ function WWebPerm(WOrm, url, db, getUserByToken, verifyClientUser, verifyAppUser
         }
 
         //userFind, 對應鍵須唯一(F-14, 規則帳本 R-MAPKEY-02): 命中多於 1 筆即拒絕, 不取首筆(取首筆等於由資料庫列序決定登入者為誰)
-        let userRs = await woItems.users.select({ [mappingBy]: vSelf, isActive: 'y' })
-        let { user: userFind, count: countFind } = pickUniqueUser(userRs)
+        //mappingBy 為 'id' 時(perm-run04, R-MAPKEY-04, O1): 後台列(from 空)對 id、外部列(from 非空)對 srcKey(外部列之 id 是本系統配發之內部主鍵, 不是登入識別); 判準單一擁有者 keyCheck.findLoginUsers
+        let { user: userFind, count: countFind } = await findLoginUsers(woItems.users, mappingBy, vSelf)
         // console.log('userFind', userFind)
 
         //check, 多筆: 只記 mappingBy 與筆數, 不記使用者之對應值(email／name 為個資); 0 筆行為不變
@@ -497,14 +494,19 @@ function WWebPerm(WOrm, url, db, getUserByToken, verifyClientUser, verifyAppUser
 
 
     //getAndVerifyClientUser
-    let getAndVerifyClientUser = async (token, from = '') => {
+    let getAndVerifyClientUser = async (token, from = '', { adminOnly = false } = {}) => {
         //基於token查找client使用者, 會基於外部getUserByToken以及perm內部users進行查找並比對
+        //adminOnly 為 true 時(經 getAndVerifyAdminUser)於完整驗證通過後另要求 perm 列為有效之系統管理員(R-ADMIN-ONLY-01); 預設 false 者(/api/getPerm)一般使用者照常
 
         //getTokenUser
         let user = await getTokenUser(token)
 
-        //verifyClientUser
-        let b = verifyClientUser(user, from)
+        //isAdmin, 於交給部署方前判定(判準 adminCheck.isAdminRow, perm 列為權威)
+        let isAdmin = isAdminRow(user)
+
+        //verifyClientUser, 部署方只收到淺層副本(perm 列之欄位皆為純量): 其函數即使改寫收到之 user(id、isAdmin…)亦不影響本函數回傳之 user——
+        //後續以 user.id 為執行身分／查權限樹, 檢查之值即使用之值(perm-run01 外審 sol#2: 否則角色取自 A、執行 id 被改成 M)
+        let b = verifyClientUser({ ...user }, from)
         if (ispm(b)) {
             b = await b
         }
@@ -516,10 +518,27 @@ function WWebPerm(WOrm, url, db, getUserByToken, verifyClientUser, verifyAppUser
             return Promise.reject(`userNoPermission`)
         }
 
+        //check admin, 一般使用者即使部署方放行亦拒絕(固定語系鍵 userNotAdmin; 只記 from, 不記 token 與使用者資料)
+        if (adminOnly && !isAdmin) {
+            srLog.error({ event: 'getAndVerifyAdminUser-error', msg: 'userNotAdmin', from })
+            return Promise.reject(`userNotAdmin`)
+        }
+
         return user
     }
 
 
+    //getAndVerifyAdminUser: 權限後台與資料通道只限系統管理員(perm-run01; 使用者 2026-10-24 裁示「系統管理員才能讀寫 4 表, 一般使用者是沒法進權限後台的, 故只能用 token 查自己權限樹」; 規則帳本 R-ADMIN-ONLY-01)
+    //在 getAndVerifyClientUser 之完整驗證(外部 getUserByToken → perm users 存在且 isActive='y' → 部署方 verifyClientUser)之後, 另要求該使用者為 perm users 表中 isAdmin='y' 且 isActive='y':
+    //perm 以自身 users 表為權威, 不採 token(getUserByToken)宣稱之 isAdmin(user 為 getTokenUser 當次新鮮讀取之 perm 列, 不快取); 不符即 reject 固定語系鍵 userNotAdmin(fail-closed), 記 srLog(只記 from, 不記 token 與使用者資料).
+    //部署方 verifyClientUser 仍照常套用(只能再收緊), 不必再以 from 區分管理員與一般使用者. 唯一不經本函數之使用者入口為 /api/getPerm(一般使用者以 token 查本人權限樹), 以及應用系統路由(verifyAppUser).
+    //判準單一擁有者 adminCheck.isAdminRow(與 requireAdmin 共用)
+    //角色於 getTokenUser 回傳當下判定(早於交給部署方 verifyClientUser), 使「檢查之值即使用之值」: 部署方函數即使修改其收到之 user 物件亦不影響角色判定; 但拒絕鍵次序為先 userNoPermission(部署方否決)後 userNotAdmin
+    let getAndVerifyAdminUser = async (token, from = '') => {
+        return await getAndVerifyClientUser(token, from, { adminOnly: true })
+    }
+
+
     //getAndVerifyAppUser
     let getAndVerifyAppUser = async (token, from = '') => {
         //基於token查找app使用者, 會基於外部getUserByToken進行查找, 故只要getUserByToken提供使用者即可, 可支援getUserByToken給予針對應用程式所產生之虛擬使用者
@@ -567,10 +586,11 @@ function WWebPerm(WOrm, url, db, getUserByToken, verifyClientUser, verifyAppUser
         //改為與登入入口對稱, 使 UI 之「是否有效」與部署層 verifyClientUser 政策對資料通道亦生效.
         //from 為 w-converhp 之 apiType('main' / 'upload-controller' / 'upload-slice' / 'download-get-filename' / 'download-get-file' / 'download'),
         //供部署層 verifyClientUser(user, from) 區分入口.
+        //perm-run01(R-ADMIN-ONLY-01): 資料通道只限系統管理員——完整驗證通過後另要求 perm 列 isAdmin='y' 且 isActive='y', 所有入口(main 之 RPC／表 select／系統函數, 上傳下載各 apiType)同一道閘; 一般使用者即使部署方放行亦拒絕(只能用 /api/getPerm 查本人權限樹)
         checkToken: async(token, from = '') => {
 
-            //getAndVerifyClientUser, reject 時 key: cannotFindUserFromToken / cannotGetUserFromPerm / userNoPermission 等
-            await getAndVerifyClientUser(token, from)
+            //getAndVerifyAdminUser, reject 時 key: cannotFindUserFromToken / cannotGetUserFromPerm / userNoPermission / userNotAdmin 等
+            await getAndVerifyAdminUser(token, from)
 
             return true
         },
@@ -625,290 +645,6 @@ function WWebPerm(WOrm, url, db, getUserByToken, verifyClientUser, verifyAppUser
     }
 
 
-    //syncAndReplaceTabs
-    let syncAndReplaceTabs = async (userId, inp, keyTable) => {
-
-        //序列化同表之並行整表 delAll+insert: 防 lost update (同 keyTable 序列化, 不同表並行)
-        //與後台整表寫入(procCore.updateTabItems)共用同表互斥鍵 tabWriteKey: 兩者各自先檢查名稱／對應鍵唯一後寫入, 鍵不同則交錯可略過 F-02／F-14(外審 sol R10);
-        //有改名或刪除而須改寫引用端時, 於內層依階層再取引用端表之鎖(同步群組／權限／標的時, 被刪除或改名者之引用須連帶清理／更新, R-REF-CASCADE-01), 皆經單一取鎖函數(R-WRITE-LOCK-02)
-        return await withTabLocks(kmx, [keyTable], async () => {
-
-            //from
-            let from = get(inp, 'from', '')
-            // console.log('from', from)
-
-            //check
-            if (!isestr(from)) {
-                console.log('inp', inp)
-                srLog.error({ event: 'syncAndReplaceTabs-error', msg: 'invalidFrom', keyTable })
-                return Promise.reject(`invalidFrom`)
-            }
-
-            //rows
-            let rows = get(inp, 'rows', [])
-            // console.log(keyTable, rows)
-
-            //check
-            if (!isearr(rows)) {
-                console.log('inp', inp)
-                console.log('keyTable', keyTable)
-                srLog.error({ event: 'syncAndReplaceTabs-error', msg: 'invalidRows', keyTable })
-                return Promise.reject(`invalidRows`)
-            }
-
-            //各列須為非空物件(規則帳本 R-ORM-05, 與後台整表寫入共用 isRowObj), 否則整批拒絕且不進 delAll:
-            //修正前非物件元素(字串、數字、null)使下方 v.from = from 拋 TypeError, 經 pm2resolve 把引擎原文外送給外部應用(R-ORM-02), 元素為 {} 時則寫入一筆自動主鍵之空白列
-            let kBadRow = rows.findIndex((v) => !isRowObj(v))
-            if (kBadRow >= 0) {
-                srLog.error({ event: 'syncAndReplaceTabs-error', msg: 'invalidRows', reason: 'rowInvalid', keyTable, from, row: kBadRow })
-                return Promise.reject(`invalidRows`)
-            }
-
-            //keyAssign／hasAssign: 後台可寫之指派欄(users.cgrups／grups.cpemis／pemis.crules; targets 無)及各列是否自帶該鍵(須於 ltdtmapping 缺鍵補 '' 之前記錄);
-            //缺該鍵者於下方保留庫內指派(F-23, 指派欄屬後台, 見 syncKeep.mjs)
-            let keyAssign = (keyTable === 'users') ? 'cgrups' : ((keyTable === 'grups') ? 'cpemis' : ((keyTable === 'pemis') ? 'crules' : null))
-            let hasAssign = (keyAssign !== null) ? markHasKey(rows, keyAssign) : null
-
-            //save from
-            rows = map(rows, (v, k) => {
-            // v.order = k + 1 //order大部分由外部給予, 不能複寫
-                v.from = from
-                return v
-            })
-
-            //ltdtmapping
-            rows = ltdtmapping(rows, ds[keyTable].keys)
-            // console.log('ltdtmapping rows', rows)
-
-            //映射到 schema 欄位後, 除伺服器管理欄(from 與建立者／建立時間／更新者／更新時間, 寫入時由伺服器覆寫)外, 沒有任何欄位帶有內容者為空白列, 整批拒絕(規則帳本 R-ORM-05; 外審 minimax#3、sol#3／#4):
-            //上方 isRowObj 只擋 {} 與非物件, {"foo":1}、{"length":5} 等「只含非 schema 欄位」之列映射後與 {} 相同, 仍會被 insert 成自動主鍵之空白列;
-            //只帶伺服器管理欄(如 {"userId":"x"})之列, 該值於寫入時被覆寫, 結果同為空白列; 欄位值為 []／{} 等空容器亦非內容.
-            //內容 = 非空字串、有限數字(0 亦是)、布林
-            let kpSrvKey = { from: true, userId: true, timeCreate: true, userIdUpdate: true, timeUpdate: true }
-            let isContent = (x) => (typeof x === 'string' && x !== '') || (typeof x === 'number' && Number.isFinite(x)) || typeof x === 'boolean'
-            let kBlank = rows.findIndex((v) => !Object.keys(v).some((k) => kpSrvKey[k] !== true && isContent(v[k])))
-            if (kBlank >= 0) {
-                srLog.error({ event: 'syncAndReplaceTabs-error', msg: 'invalidRows', reason: 'rowBlank', keyTable, from, row: kBlank })
-                return Promise.reject(`invalidRows`)
-            }
-
-            //名稱／標的 id 須為非空字串(規則帳本 R-SYNC-NAME-01, 主控複審 R2): 比照後台整表寫入之 ckKey(procCore.mjs: isestr(value)),
-            //grups／pemis 之 name、targets 之 id 缺漏、空字串、非字串(數字、布林、null)一律整批拒收, 於 delAll 之前, 該 from 與他 from 之既有列不變.
-            //why: 修正前 name:'' 之群組／權限可入庫, 伺服端 arrFinder 以 === 採納之(授權有效), 編輯器(cvKpToObj／doSave)視空名稱為無效, 管理者存檔即移除該授權
-            //(移除 AND 限制時等於增權); 與後台路徑(ckKey 拒收空名稱)不對稱. users 不在範圍(name 可重複); 不比照 ckKey 之重複偵測(複審範圍僅「非空」)
-            let keyName = (keyTable === 'targets') ? 'id' : ((keyTable === 'grups' || keyTable === 'pemis') ? 'name' : null)
-            if (keyName !== null) {
-                let kName = rows.findIndex((v) => !isestr(get(v, keyName)))
-                if (kName >= 0) {
-                    srLog.error({ event: 'syncAndReplaceTabs-error', msg: 'invalidRows', reason: (keyName === 'id') ? 'idInvalid' : 'nameInvalid', keyTable, from, row: kName, field: keyName })
-                    return Promise.reject(`invalidRows`)
-                }
-            }
-
-            //群組／權限名稱唯一(F-02, 規則帳本 R-NAME-UNIQ-01, ADR-034), 本批 rows 內 name 精確 === 重複整批拒收(他 from 已使用者見下方 nameOtherFrom), 於 delAll 之前, 該 from 與他 from 之既有列不變.
-            //why: 授權以名稱查找(arrFinder 取第一個同名列), 同名並存即授權取決於資料庫列序; 後台 ckKey／updateTabItems 早已拒同名, 外部同步原不拒(ADR-031 決定 4 曾明載不比照), 兩入口不對稱.
-            //外部應用只收固定語系鍵 invalidRows(規則帳本 R-ORM-02); targets 之 id 為主鍵(validateRowsBeforeWrite 已查批內重複), users 之 name 允許重複, 皆不在此
-            if (keyName === 'name') {
-                let kDup = findDupIndex(rows, 'name')
-                if (kDup >= 0) {
-                    srLog.error({ event: 'syncAndReplaceTabs-error', msg: 'invalidRows', reason: 'nameDuplicate', keyTable, from, row: kDup, field: 'name' })
-                    return Promise.reject(`invalidRows`)
-                }
-            }
-
-            //users 對應鍵批內檢查(F-14, 規則帳本 R-MAPKEY-01, ADR-034): mappingBy 為 'email'／'name' 時, 每個 isActive==='y' 之列該欄位須非空字串且批內唯一(精確 ===); 'id'(預設)不另檢查;
-            //只有「對應鍵」才是登入查找(getTokenUser)之鍵, 其唯一性才是安全前提——預設部署之 email 可空／可重複, 不得因新規則使其外部同步全數失敗. log 不記對應值(個資)
-            if (keyTable === 'users') {
-                let mk = checkMapKeyBatch(rows, mappingBy)
-                if (mk !== null) {
-                    srLog.error({ event: 'syncAndReplaceTabs-error', msg: 'invalidRows', reason: mk.reason, keyTable, from, row: mk.k, field: mappingBy })
-                    return Promise.reject(`invalidRows`)
-                }
-            }
-
-            //寫入前驗證(規則帳本 R-ORM-01, ADR-026): 於 delAll 之前擋下可預判之寫入失敗, 該 from 之既有列不變(ADR-008 防誤清源).
-            //why: 先 delAll 再 insert, 而 w-serv-orm 1.1.8 起對「會被 clearXSS 改寫之主鍵」整批拒絕、LMDB 對 > 1978 B 之主鍵整批拒絕,
-            //修正前遇之即該 from 之既有列全數清空(2026-10-14 V4/V7 實測). 主鍵問題 → invalidRows; 任一字串欄位含標記 → htmlMarkupNotAllowed
-            let ve = validateRowsBeforeWrite(rows)
-            if (ve !== null) {
-                let key = (ve.reason === 'htmlMarkup') ? 'htmlMarkupNotAllowed' : 'invalidRows'
-                srLog.error({ event: 'syncAndReplaceTabs-error', msg: key, reason: ve.reason, keyTable, from, row: ve.k, field: ve.field })
-                return Promise.reject(key)
-            }
-
-            //跨 from 同鍵(規則帳本 R-SYNC-01): 本批有給之主鍵若已屬其他 from, 整批拒絕且不進 delAll(本 from 與他 from 之既有列皆不變).
-            //why: insert 對已存在之主鍵略過而整批仍回 success, 該列不會寫入本 from(靜默遺失); w-serv-orm 1.1.11 起數字主鍵存為其字串形式(原被換成隨機主鍵),
-            //以流水號為主鍵之各應用即互撞(2026-10-14 w-serv-orm 實測). 此處直呼 woItems(不經 procOrm 之轉型), 查詢條件一律用 String(id)(R-ORM-04);
-            //同 from 之既有列不算衝突(隨後由 delAll 重寫); 本段與 delAll／insert 同在 kmx 內(同表之並行同步已序列化)
-            let keyOfId = (v) => {
-                let id = get(v, 'id')
-                return (isestr(id) || (typeof id === 'number' && Number.isFinite(id))) ? String(id) : null
-            }
-            let sids = rows.map(keyOfId).filter((s) => s !== null)
-            if (sids.length > 0) {
-                let rsExist = null
-                try {
-                    rsExist = await woItems[keyTable].select({ id: { $in: sids } })
-                }
-                catch (err) {
-                    let raw = (typeof err === 'string') ? err : ((err && err.message) || String(err))
-                    let key = toOutKey(err, 'anUnexpectedErrorOccurred') //尚未寫入任何資料, 不回 saveWriteFail
-                    srLog.error({ event: 'syncAndReplaceTabs-error', msg: key, raw, keyTable, from, step: 'select' })
-                    return Promise.reject(key)
-                }
-                let fromById = new Map()
-                for (let v of rsExist) {
-                    fromById.set(String(v.id), v.from)
-                }
-                let k = rows.findIndex((v) => {
-                    let s = keyOfId(v)
-                    return s !== null && fromById.has(s) && fromById.get(s) !== from
-                })
-                if (k >= 0) {
-                    srLog.error({ event: 'syncAndReplaceTabs-error', msg: 'invalidRows', reason: 'idOtherFrom', keyTable, from, row: k, field: 'id' })
-                    return Promise.reject('invalidRows')
-                }
-            }
-
-            //跨 from 同名／同對應鍵(F-02／F-14, 規則帳本 R-NAME-UNIQ-01／R-MAPKEY-01): grups／pemis 之 name、users 於 mappingBy 為 email／name 時之該欄位(僅 active 列),
-            //已為其他 from 之既有列使用 → 整批拒絕且不進 delAll; 同 from 之既有列不算衝突(隨後由 delAll 重寫). 先 select 後比對, select 失敗之處置同上段(toOutKey, 未寫入任何資料)
-            let keyOther = (keyName === 'name') ? 'name' : ((keyTable === 'users') ? mapKeyOf(mappingBy) : null)
-            if (keyOther !== null) {
-                let rsAll = null
-                try {
-                    rsAll = await woItems[keyTable].select()
-                }
-                catch (err) {
-                    let raw = (typeof err === 'string') ? err : ((err && err.message) || String(err))
-                    let key = toOutKey(err, 'anUnexpectedErrorOccurred') //尚未寫入任何資料, 不回 saveWriteFail
-                    srLog.error({ event: 'syncAndReplaceTabs-error', msg: key, raw, keyTable, from, step: 'select' })
-                    return Promise.reject(key)
-                }
-                let kOther = findKeyOtherFrom(rows, rsAll, from, keyOther, { onlyActive: keyTable === 'users' })
-                if (kOther >= 0) {
-                    srLog.error({ event: 'syncAndReplaceTabs-error', msg: 'invalidRows', reason: (keyTable === 'users') ? 'mapKeyOtherFrom' : 'nameOtherFrom', keyTable, from, row: kOther, field: keyOther })
-                    return Promise.reject('invalidRows')
-                }
-            }
-
-            //外部同步 payload 缺指派欄鍵之列保留庫內值(F-23; 主控定案: 指派欄屬後台, 同步不得清掉後台指派; 含該鍵則以外部為準): 修正前 ltdtmapping 缺鍵補 ''、delAll＋insert 即清空後台已指派者.
-            //三個指派欄(users.cgrups／grups.cpemis／pemis.crules; run08 起 cpemis／crules 比照 cgrups)皆是; 只在確有缺鍵之列時才讀庫內(同一 from).
-            //users: 對應先依 id、無 id 者依 mappingBy(email／name)恰命中 1 筆, 對不到者視為新使用者(維持 ''), 對應鍵矛盾者不保留(keepAssignOnMissing);
-            //grups／pemis: 無登入對應鍵, 實體身分依 id(無 id 者依名稱恰 1 筆; 改名而 cascadeRename 為假者不保留; keepAssignByEntity). select 失敗之處置同上段(toOutKey, 尚未寫入任何資料)
-            if (hasAssign !== null && hasAssign.some((b) => b === false)) {
-                let rsSame = null
-                try {
-                    rsSame = await woItems[keyTable].select({ from }) //此處 keyTable 為 users／grups／pemis(hasAssign 非 null); users 非登入查找, 不經 pickUniqueUser(SITE-KC-004 只管登入反查)
-                }
-                catch (err) {
-                    let raw = (typeof err === 'string') ? err : ((err && err.message) || String(err))
-                    let key = toOutKey(err, 'anUnexpectedErrorOccurred')
-                    srLog.error({ event: 'syncAndReplaceTabs-error', msg: key, raw, keyTable, from, step: 'select' })
-                    return Promise.reject(key)
-                }
-                //isKeepable: 保留值於 delAll 之前須再通過一次寫入前驗證(上方 validateRowsBeforeWrite 看到的是補出之空字串, 外審 sol R4); 不過者不保留(視為空, 收嚴), 只記筆數
-                let isKeepable = (val) => validateRowsBeforeWrite([{ id: 'keep', [keyAssign]: val }]) === null
-                let kr = (keyTable === 'users') ? keepAssignOnMissing({ rows, hasKey: hasAssign, rowsOldSameFrom: rsSame, mappingBy, isKeepable }) : keepAssignByEntity({ rows, hasKey: hasAssign, rowsOldSameFrom: rsSame, key: keyAssign, cascadeRename, isKeepable })
-                rows = kr.rows
-                if (kr.nKeep > 0) {
-                    srLog.info({ event: 'syncAndReplaceTabs-keepAssign', keyTable, from, field: keyAssign, n: kr.nKeep })
-                }
-                if (kr.nSkip > 0) {
-                    srLog.warn({ event: 'syncAndReplaceTabs-keepAssign-skip', keyTable, from, field: keyAssign, n: kr.nSkip, reason: 'notKeepable' })
-                }
-                if (kr.nConflict > 0) {
-                    srLog.warn({ event: 'syncAndReplaceTabs-keepAssign-skip', keyTable, from, field: keyAssign, n: kr.nConflict, reason: (keyTable === 'users') ? 'mapKeyConflict' : 'identityConflict' }) //users: 對應鍵與 id 指向不同使用者; grups／pemis: 同名多筆無從對應或改名而引用不跟著改; 指派不移轉而清空(收嚴須附提示; 不含個資值)
-                }
-            }
-
-            //引用連帶(適用表 m／n, R-REF-CASCADE-01): 同步 grups／pemis／targets 時, 同一 from 內依穩定 id 判定——同 id 異名＝改名級聯、舊 id 不在本批＝刪除而連帶清理引用(寫入後仍存續之同名者不清理);
-            //未帶 id 之列(ORM 每次補隨機主鍵)改依名稱對應(見 buildSyncRowsNew). 預檢(新名撞懸空名、歷史同名組改名、容器內相撞、改寫後欄位驗證)於 delAll 之前, 被拒整批零變更;
-            //外部應用只收固定語系鍵 invalidRows／htmlMarkupNotAllowed(R-ORM-02), 動態原因入 srLog. select 失敗之處置同上段(toOutKey, 未寫入任何資料).
-            //是否須改寫引用端只依本表新舊列判定(diffRefTargets), 持有本表鎖之下即可決定是否再取引用端表之鎖(R-WRITE-LOCK-02); 取齊鎖之後才讀取引用端、規劃與預檢
-            let rowsPlan = null
-            let kind = null
-            if (Object.prototype.hasOwnProperty.call(REF_OF, keyTable)) {
-                try {
-                    let rowsOld = await woItems[keyTable].select()
-                    rowsPlan = { rowsOld, rowsNew: buildSyncRowsNew(keyTable, rowsOld, rows, from) }
-                }
-                catch (err) {
-                    let raw = (typeof err === 'string') ? err : ((err && err.message) || String(err))
-                    let key = toOutKey(err, 'anUnexpectedErrorOccurred')
-                    srLog.error({ event: 'syncAndReplaceTabs-error', msg: key, raw, keyTable, from, step: 'select' })
-                    return Promise.reject(key)
-                }
-                kind = diffRefTargets({ keyTable, rowsOld: rowsPlan.rowsOld, rowsNew: rowsPlan.rowsNew, opt: { cascadeRename } })
-
-                //外部 id 不穩定之偵測(主控定案: 不加開關; 同一 from 同一批內出現「同名異 id」＝疑似 id 重編, id 消失視為刪除會每次清理引用而可能抹掉後台指派): 記 warn log(不記個資值, 只記筆數)
-                //並登錄供 getWebInfor.syncWarns 於頁面提示; 之後同一(表, from)之同步已無此情形即清除提示. 只適用有 name 之 grups／pemis(users 之 name 可重複, targets 之 id 即名稱)
-                if (keyTable === 'grups' || keyTable === 'pemis') {
-                    let nRenum = countIdRenumber(rowsPlan.rowsOld.filter((o) => o !== null && typeof o === 'object' && o.from === from), rows)
-                    setSyncWarn(keyTable, from, nRenum)
-                    if (nRenum > 0) {
-                        srLog.warn({ event: 'syncAndReplaceTabs-idRenumber', keyTable, from, n: nRenum })
-                    }
-                }
-            }
-
-            //doWrite: delAll from, insert; ORM／I/O 失敗之原文只入 srLog, 外部應用收 saveWriteFail(規則帳本 R-ORM-02); 引用端先寫、失敗補償還原(cascadeWrite.mjs)
-            let doWrite = async (plan, holdersOld) => {
-                let r = null
-                try {
-                    r = await writeWithCascade({
-                        plan,
-                        holdersOld,
-                        woItems,
-                        procOrm,
-                        userId,
-                        srLog,
-                        writeMain: async () => {
-                            await woItems[keyTable].delAll({ from })
-                            return await procOrm(userId, keyTable, 'insert', rows) //須使用procOrm才有辦法自動給予相關欄位
-                        },
-                    })
-                }
-                catch (err) {
-                    let raw = (typeof err === 'string') ? err : ((err && err.message) || String(err))
-                    let key = toOutKey(err)
-                    srLog.error({ event: 'syncAndReplaceTabs-error', msg: key, raw, keyTable, from })
-                    return Promise.reject(key)
-                }
-                // console.log('r', r)
-                return r
-            }
-
-            //有改名或刪除: 再取引用端表之鎖, 讀取引用端、規劃、預檢後寫入
-            if (kind !== null && (kind.renames.length > 0 || kind.delNames.length > 0)) {
-                let holder = REF_OF[keyTable].holder
-                return await withTabLocks(kmx, [holder], async () => {
-                    let holdersOld = null
-                    try {
-                        holdersOld = await woItems[holder].select()
-                    }
-                    catch (err) {
-                        let raw = (typeof err === 'string') ? err : ((err && err.message) || String(err))
-                        let key = toOutKey(err, 'anUnexpectedErrorOccurred')
-                        srLog.error({ event: 'syncAndReplaceTabs-error', msg: key, raw, keyTable, from, step: 'select' })
-                        return Promise.reject(key)
-                    }
-                    let plan = planRefChanges({ keyTable, rowsOld: rowsPlan.rowsOld, rowsNew: rowsPlan.rowsNew, holdersOld, opt: { cascadeRename } })
-                    let errPlan = plan.err !== null ? plan.err : checkCascadePlan(plan)
-                    if (errPlan !== null) {
-                        let key = (errPlan === 'htmlMarkupNotAllowed') ? 'htmlMarkupNotAllowed' : 'invalidRows'
-                        srLog.error({ event: 'syncAndReplaceTabs-error', msg: key, reason: errPlan, keyTable, from })
-                        return Promise.reject(key)
-                    }
-                    return await doWrite(plan, holdersOld)
-                }, [keyTable])
-            }
-
-            return await doWrite(null, [])
-
-        })
-    }
-
-
     //getGenUserByKV
     let getGenUserByKV = async(keyUser, valueUser) => {
 
@@ -925,6 +661,46 @@ function WWebPerm(WOrm, url, db, getUserByToken, verifyClientUser, verifyAppUser
     }
 
 
+    //requireAdmin: 函數層級之角色檢查(perm-run03 範圍四; dspec/使用者身分驗證原則.md 二.4「函數層級須另檢查角色, 不得只靠部署方之授權設定把關」; w-web呼叫者身分驗證.md C2, 使用者 2026-10-23 裁示採②):
+    //改變狀態之 kpFunExt 函數(updateTargets／updatePemis／updateGrups／updateUsers; getWebInfor、getStaEvent、getStaEventTable 為唯讀不在此列)限 perm users 表中有效(isActive='y')且 isAdmin='y' 之使用者.
+    //perm 以自身 users 表為權威, 不採 token(getUserByToken)宣稱之 isAdmin(同 getTokenUser); userId 為 getUserIdByToken 回傳之 perm 內 id, 此處再新鮮讀取一次(角色可能於連線後被改, 不信任快取).
+    //不符即 reject 固定錯誤鍵 userNotAdmin、零寫入(先於 lockSave／表鎖／任何讀庫), 記 srLog(只記函數名與 userId, 不記 token 與使用者資料); 讀取失敗(ORM 例外)一律視同不符(fail-closed)
+    let requireAdmin = async (userId, funcName) => {
+        let u = null
+        try {
+            u = await getGenUserByKV('id', userId)
+        }
+        catch (err) {
+            u = null
+        }
+        if (!isAdminRow(u)) { //縱深防禦: 資料通道已於連線閘與執行身分要求管理員(R-ADMIN-ONLY-01), 此處對新鮮讀取之列再判一次(連線後角色被降級之競態)
+            srLog.error({ event: 'requireAdmin-error', msg: 'userNotAdmin', funcName, userId })
+            return Promise.reject('userNotAdmin')
+        }
+        return u
+    }
+
+
+    //resolvePermUserId: /api/getPermUserInfor 之 userId(外部應用傳入)依登入對應解析(perm-run05, 規則帳本 R-MAPKEY-05; 主控 2026-10-24 收件裁示②):
+    //mappingBy 為 'id' 時, 外部應用手上只有外部使用者 id(即登入識別: 外部列對 srcKey、後台列對 id), 不知本系統配發之內部 id, 故與登入入口同一判準(keyCheck.findLoginUsers)解析:
+    //命中多筆(不論有效與否)→ 拒絕 ambiguousUserFromPerm(不取首筆); 恰 1 筆有效 → 回 { userId: 其內部 id, userFind: 該列 };
+    //其餘(查無或恰 1 筆停用)→ 回 { userId: null, userFind: null }(視同查無使用者, 回全停用之空權限, 與修正前查無使用者行為相同);
+    //以解析出之列直接算權限, 不再以內部 id 重讀(外審 sol 第一輪#2: 解析與重讀之間該列可被刪除、同 id 被另一人佔用, 重讀會取得另一人之權限);
+    //'email'／'name' 時 userId 維持內部 id(行為不變, userFind 為 undefined 表示照舊以 id 讀取). 僅此路由使用: /api/getPerm 之 userIdSelf 已是 getTokenUser 回傳之內部 id, 不得再解析.
+    let resolvePermUserId = async (userIdFind) => {
+        if (mapKeyOf(mappingBy) !== null) {
+            return { userId: userIdFind, userFind: undefined }
+        }
+        let { user, count } = await findLoginUsers(woItems.users, mappingBy, userIdFind)
+        if (count > 1) {
+            console.log('mappingBy', mappingBy, 'count', count)
+            srLog.error({ event: 'api/getPermUserInfor-error', msg: 'ambiguousUserFromPerm', mappingBy, count })
+            return Promise.reject('ambiguousUserFromPerm')
+        }
+        return iseobj(user) ? { userId: user.id, userFind: user } : { userId: null, userFind: null }
+    }
+
+
     //getGenUserByUserId
     let getGenUserByUserId = async(userId) => {
 
@@ -941,10 +717,10 @@ function WWebPerm(WOrm, url, db, getUserByToken, verifyClientUser, verifyAppUser
 
 
     //getGenUserAndRulesByUserId
-    let getGenUserAndRulesByUserId = async (userId) => {
+    let getGenUserAndRulesByUserId = async (userId, userPre = undefined) => {
 
-        //userFind
-        let userFind = await getGenUserByUserId(userId)
+        //userFind, userPre 非 undefined 時(含 null＝查無)為呼叫端已解析之列, 直接採用不重讀(resolvePermUserId); 否則依 userId 讀取
+        let userFind = (userPre !== undefined) ? userPre : await getGenUserByUserId(userId)
         // console.log('userFind', userFind)
 
         //grups
@@ -1054,8 +830,8 @@ function WWebPerm(WOrm, url, db, getUserByToken, verifyClientUser, verifyAppUser
                         return Promise.reject(`tokenNoPermission`)
                     }
 
-                    //getAndVerifyClientUser
-                    let user = await getAndVerifyClientUser(token, 'getUserByToken')
+                    //getAndVerifyAdminUser, 後台登入檢查只限系統管理員(perm-run01, R-ADMIN-ONLY-01): 一般使用者即使部署方放行亦拒絕(userNotAdmin, 前端顯示「無權進入權限後台」); 一般使用者查本人權限樹走 /api/getPerm
+                    let user = await getAndVerifyAdminUser(token, 'getUserByToken')
                     // console.log('user', user)
 
                     //check
@@ -1129,8 +905,9 @@ function WWebPerm(WOrm, url, db, getUserByToken, verifyClientUser, verifyAppUser
                         return Promise.reject(`tokenNoPermission`)
                     }
 
-                    //getGenUserAndRulesByUserId, 查找到的client使用者與權限
-                    let userWithRulesSelf = await getGenUserAndRulesByUserId(userIdSelf)
+                    //getGenUserAndRulesByUserId, 查找到的client使用者與權限; 第2參傳入驗證時取得之列(userSelf), 直接採用不以 id 重讀:
+                    //驗證與重讀之間(含 verifyClientUser 為 async 之等待期間)該列可能被改登入鍵或刪除後同 id 換人, 重讀會回另一人之資料與權限樹(同 /api/getPermUserInfor 之 resolvePermUserId, perm-run01 外審 sol#3)
+                    let userWithRulesSelf = await getGenUserAndRulesByUserId(userIdSelf, userSelf)
                     // console.log('getGenUserAndRulesByUserId', r)
 
                     //check
@@ -1206,8 +983,11 @@ function WWebPerm(WOrm, url, db, getUserByToken, verifyClientUser, verifyAppUser
                         return Promise.reject(`tokenNoPermission`)
                     }
 
-                    //getGenUserAndRulesByUserId, 查找到的使用者與權限
-                    let userWithRulesFind = await getGenUserAndRulesByUserId(userIdFind)
+                    //resolvePermUserId, mappingBy 為 id 時依登入對應解析出使用者列(外部列傳 srcKey、後台列傳 id; 多筆拒絕), email／name 時維持內部 id
+                    let userPerm = await resolvePermUserId(userIdFind)
+
+                    //getGenUserAndRulesByUserId, 查找到的使用者與權限(已解析之列直接採用)
+                    let userWithRulesFind = await getGenUserAndRulesByUserId(userPerm.userId, userPerm.userFind)
                     // console.log('getGenUserAndRulesByUserId', userWithRulesFind)
 
                     //check
@@ -1303,7 +1083,7 @@ function WWebPerm(WOrm, url, db, getUserByToken, verifyClientUser, verifyAppUser
                     let inp = await parsePayload(req)
 
                     //syncAndReplaceTabs
-                    let r = await syncAndReplaceTabs(userId, inp, keyTable)
+                    let r = await sc.syncAndReplaceTabs(userId, inp, keyTable)
 
                     //info
                     srLog.info({ event: 'api/syncAndReplaceTabs-success', userId, keyTable })
@@ -1342,6 +1122,10 @@ function WWebPerm(WOrm, url, db, getUserByToken, verifyClientUser, verifyAppUser
         verifyConn: async ({ apiType, authorization, query, headers, req }) => {
             // console.log('verifyConn', `apiType[${apiType}]`, `authorization[${authorization}]`)
 
+            //身分驗證責任(dspec/使用者身分驗證原則.md 第三節, 使用方套件標準註解): 框架(w-converhp、w-serv-hapi、w-serv-webdata、w-serv-orm)不驗證 token, 一律由本套件負責.
+            //連線閘(verifyConn)與執行身分(getUserIdByToken)皆須完整驗證(token 有效、本系統使用者存在且啟用、部署方授權); hapi apis 路由各自驗證; 函數層級另檢查角色或成員(updateXxx 限 perm users 表之 isAdmin='y', requireAdmin); 公開入口只限列名者.
+            //本函數: 驗連線標頭之 token(getAndVerifyAdminUser: 外部 getUserByToken → perm users 存在且 isActive='y' → 部署方 verifyClientUser(user, apiType) → perm 列 isAdmin='y', R-ADMIN-ONLY-01: 權限後台與資料通道只限系統管理員, 一般使用者查本人權限樹走 /api/getPerm).
+
             //token
             let token = strdelleft(authorization, 7) //刪除Bearer
             // console.log('token', token)
@@ -1391,11 +1175,25 @@ function WWebPerm(WOrm, url, db, getUserByToken, verifyClientUser, verifyAppUser
         },
         getUserIdByToken: async (token) => { //可使用async或sync函數
             // console.log('getUserIdByToken', token)
-            let user = await getUserByToken(token)
+
+            //身分驗證責任(dspec/使用者身分驗證原則.md 第三節, 使用方套件標準註解; 規則 w-web呼叫者身分驗證.md 規則 4): 框架(w-converhp、w-serv-hapi、w-serv-webdata、w-serv-orm)不驗證 token, 一律由本套件負責.
+            //連線閘(verifyConn)與執行身分(getUserIdByToken)皆須完整驗證(token 有效、本系統使用者存在且啟用、部署方授權); hapi apis 路由各自驗證; 函數層級另檢查角色或成員; 公開入口只限列名者.
+            //本函數: 資料通道只傳遞 token, 反查使用者即驗證身分之步驟(w-serv-orm 1.1.10 起 ORM 層不做使用者檢查): 與連線閘同等完整——經 getAndVerifyAdminUser(外部 getUserByToken → perm users 存在且 isActive='y' → 部署方 verifyClientUser → perm 列 isAdmin='y'),
+            //任一關不過即 reject(框架據此不執行函數, fail-closed)並記 srLog, 不回顯 token 與使用者資料. 請求標頭與本體 __sysToken__ 縱為不同 token, 兩個身分亦各經完整驗證(框架不比對兩 token).
+            //回傳 perm users 表內該使用者之 id(非外部 token 宣稱之 id): 稽核欄位(userId／userIdUpdate)與函數層級角色檢查(requireAdmin)皆以 perm 內之列為準; mappingBy 為 email／name 時兩者可不同.
+            //from 取 'main': 本函數只在資料通道 RPC／表操作(apiType 'main')之執行身分反查時被框架呼叫(上傳下載通道無監聽), 與連線閘對同一請求所用之 apiType 一致, 使部署方 verifyClientUser 依 from 分流之政策兩處一致, 不引入新的 from 值.
+            //perm-run01(R-ADMIN-ONLY-01): 與連線閘同為「只限系統管理員」——另要求 perm 列 isAdmin='y' 且 isActive='y'(getAndVerifyAdminUser), 否則 reject userNotAdmin, 框架即不執行函數(含唯讀函數與表 select).
+            let user = null
+            try {
+                user = await getAndVerifyAdminUser(token, 'main')
+            }
+            catch (err) {
+                let key = toOutKey(err, 'cannotFindUserId') //已知語系鍵原樣(cannotFindUserFromToken／cannotGetUserFromPerm／userNoPermission／userNotAdmin 等), 其餘(ORM／I/O 原文、Error)一律 cannotFindUserId, 不外送原文
+                srLog.error({ event: 'getUserIdByToken-error', msg: key })
+                return Promise.reject(key)
+            }
             let userId = get(user, 'id', '')
             if (!isestr(userId)) {
-                console.log('token', maskTok(token))
-                console.log('userId', userId)
                 srLog.error({ event: 'getUserIdByToken-error', msg: 'cannotFindUserId' })
                 return Promise.reject(`cannotFindUserId`)
             }
@@ -1407,28 +1205,39 @@ function WWebPerm(WOrm, url, db, getUserByToken, verifyClientUser, verifyAppUser
         //operOrm: procOrm 之包裝(輸入為 userId, tableName, methodName, input), ORM 拒絕之原文只入 srLog、對前端回 key(規則帳本 R-ORM-02)
         operOrm: wrapOperOrm(procOrm, { srLog }),
         tableNamesExec,
-        //資料通道只開 select(ADR-026、ADR-015 Update; 規則帳本 R-WSD-01): 前端同步只用 select, 寫入一律經 kpFunExt 之 updateXxx(lockSave、kmx、寫入前驗證、整表比對);
+        //資料通道只開 select(ADR-026、ADR-015 Update; 規則帳本 R-WSD-01): 前端同步只用 select, 寫入一律經 kpFunExt 之 updateXxx(lockSave、表鎖、寫入前驗證、整表比對);
         //裸 insert/save/del/delAll 繞過上述不變式, 2026-10-14 起不開放(直呼回 invalid func[表名.方法]); 對自寫客戶端直呼裸表操作之部署方為行為變更(README Upgrade Notes)
         methodsExec: ['select'],
         //authorizeExec: w-serv-webdata 1.1.7 起 useDbOrm:true 必填; 只對已取得 userId 之 select 放行(methodsExec 之外之第二道), 拒絕記 srLog event 'authorizeExec'.
-        //連線者身分之授權在 verifyConn(getAndVerifyClientUser), 此處不重做
+        //連線者身分之授權在 verifyConn(getAndVerifyAdminUser: 完整驗證＋限系統管理員), 此處不重做
         authorizeExec: createAuthorizeExec({ srLog }),
         tableNamesSync,
         kpFunExt: { //接收參數第1個為userId, 之後才是前端給予參數
 
             getWebInfor,
 
-            //updateXxx 第 3 參 opt 為用戶端給之 { baseline }(草稿載入基準, F-26, R-BASELINE-01), 其餘鍵一律不採納(pickKeysOnly 等為伺服端設定); 未給(舊客戶端)見 procCore 之處置
-            updateTargets: (userId, rows, opt) => pc.updateTargets(userId, rows, opt),
-            updatePemis: (userId, rows, opt) => pc.updatePemis(userId, rows, opt),
-            updateGrups: (userId, rows, opt) => pc.updateGrups(userId, rows, opt),
+            //updateXxx 第 3 參 opt 為用戶端給之 { baseline, returnRows }(草稿載入基準, F-26, R-BASELINE-01; 是否於成功回傳附寫入後之列, 規格第 8 節), 其餘鍵一律不採納(pickKeysOnly 等為伺服端設定, 更不轉給 procOrm); 未給(舊客戶端)見 procCore 之處置
+            //四個寫入函數皆先經 requireAdmin(函數層級角色檢查, perm-run03 範圍四): 非 perm users 表中有效之系統管理員 → userNotAdmin、零寫入
+            updateTargets: async (userId, rows, opt) => {
+                await requireAdmin(userId, 'updateTargets')
+                return await pc.updateTargets(userId, rows, opt)
+            },
+            updatePemis: async (userId, rows, opt) => {
+                await requireAdmin(userId, 'updatePemis')
+                return await pc.updatePemis(userId, rows, opt)
+            },
+            updateGrups: async (userId, rows, opt) => {
+                await requireAdmin(userId, 'updateGrups')
+                return await pc.updateGrups(userId, rows, opt)
+            },
             //updateUsers, modeEditUsers='for:grups' 時 API 與 UI 一致只採納既有使用者之 cgrups 變更, 身分欄/新增/刪除/順序以資料庫為準
-            updateUsers: (userId, rows, optClient) => {
-                let opt = (optClient !== null && typeof optClient === 'object' && optClient.baseline !== undefined && optClient.baseline !== null) ? { baseline: optClient.baseline } : {}
+            updateUsers: async (userId, rows, optClient) => {
+                await requireAdmin(userId, 'updateUsers')
+                let opt = pickClientOpt(optClient)
                 if (modeEditUsers === 'for:grups') {
                     opt.pickKeysOnly = ['cgrups']
                 }
-                return pc.updateUsers(userId, rows, opt)
+                return await pc.updateUsers(userId, rows, opt)
             },
 
             getStaEvent: async (userId, timeLength, timeInterval) => {