w-web-sso 1.1.12 → 1.1.13

package/server/procCore.mjs

@@ -7,6 +7,8 @@ import size from 'lodash-es/size.js'
 import keys from 'lodash-es/keys.js'
 import filter from 'lodash-es/filter.js'
 import isEqual from 'lodash-es/isEqual.js'
+import isPlainObject from 'lodash-es/isPlainObject.js'
+import { BASELINE_REJECT, digestRow, compareBaseline, isBaselineValid, pickWriteRow, getRejectKey } from 'w-serv-orm/src/baseline.mjs'
 import genIDSeq from 'wsemi/src/genIDSeq.mjs'
 import iseobj from 'wsemi/src/iseobj.mjs'
 import isestr from 'wsemi/src/isestr.mjs'
@@ -24,7 +26,6 @@ import j2o from 'wsemi/src/j2o.mjs'
 import strleft from 'wsemi/src/strleft.mjs'
 import strright from 'wsemi/src/strright.mjs'
 import strdelright from 'wsemi/src/strdelright.mjs'
-import ltdtDiffByKey from 'wsemi/src/ltdtDiffByKey.mjs'
 import ltdtmapping from 'wsemi/src/ltdtmapping.mjs'
 import haskey from 'wsemi/src/haskey.mjs'
 import arrHas from 'wsemi/src/arrHas.mjs'
@@ -46,12 +47,91 @@ import createLockSave from './lockSave.mjs'
 import ormWrite from './ormWrite.mjs'
 import { maskToken, maskKv, keysUserQuery, capText } from './srLog.mjs'
 import { hasAppPerm, isAppPermsValue, normAppPerms } from '../src/appPerms.mjs'
+import contracts from '../src/writeContracts/index.mjs'
 
 
 //keysUserCredential: users 表之憑證欄(密碼雜湊 / 註冊驗證用 token), 對外介接輸出一律剝除 (ADR-068); 新增憑證欄時於此登錄
 let keysUserCredential = ['password', 'tokenVerify']
 
 
+//kpSaveRejectKey: 寫入契約之拒收鍵(w-serv-orm baseline.mjs 之 BASELINE_REJECT, 固定英文) → 本套件語系鍵 (procLang), 一律提示重新載入 (R-CONC-03 規則 5)
+let kpSaveRejectKey = Object.create(null)
+kpSaveRejectKey[BASELINE_REJECT.mismatch] = 'saveStale'
+kpSaveRejectKey[BASELINE_REJECT.rowNotFound] = 'saveRowNotFound'
+kpSaveRejectKey[BASELINE_REJECT.format] = 'saveBaselineFormat'
+
+
+//getSaveRejectKey: 由被 reject 之值取語系鍵; 非契約拒收者回 null. 取鍵一律用核心之 getRejectKey (procOrm 為字串, guardWrite 為帶 key 之 Error)
+function getSaveRejectKey(err) {
+    let k = getRejectKey(err)
+    if (typeof k === 'string' && kpSaveRejectKey[k] !== undefined) {
+        return kpSaveRejectKey[k]
+    }
+    return null
+}
+
+
+//copyBaseline: 基準之防禦性複製, 只取資料屬性(RPC 之 JSON 不會帶存取器, 行程內直接呼叫才可能): 外層與各二元項須為陣列且二元項長度恰為 2,
+//存取器 / 洞 / 取值例外一律回 null; 複製後之驗證與其後使用皆不再觸及客戶端物件, 存取器不被執行
+function copyBaseline(b) {
+    try {
+        if (!Array.isArray(b)) {
+            return null
+        }
+        let out = []
+        for (let i = 0; i < b.length; i++) {
+            let dI = Object.getOwnPropertyDescriptor(b, i)
+            if (dI === undefined || !('value' in dI) || !Array.isArray(dI.value) || dI.value.length !== 2) {
+                return null
+            }
+            let d0 = Object.getOwnPropertyDescriptor(dI.value, 0)
+            let d1 = Object.getOwnPropertyDescriptor(dI.value, 1)
+            if (d0 === undefined || d1 === undefined || !('value' in d0) || !('value' in d1)) {
+                return null
+            }
+            out.push([d0.value, d1.value])
+        }
+        return out
+    }
+    catch (err) {
+        return null
+    }
+}
+
+
+//parseSaveOpt: 驗證前端經 RPC 送入之第 4 參數(clientOpt)並自組伺服端使用之基準; opt 只由伺服端自組, 不展開客戶端物件 (規格 §6).
+//- undefined: 不帶基準(app 權杖直呼、已開啟之舊版頁面, 本 major 允許, 後者蓋前者), 回 {}
+//- 其餘一律須為純物件且只含白名單鍵(users / ips: baseline; tokens: baseline 與 baselineSession 兩者皆須有), 基準格式或版本不識 → baselineFormat; 不得降級為不帶基準
+//回傳 { baseline, baselineSession } 或 { err: 'baselineFormat' }
+function parseSaveOpt(woName, clientOpt) {
+    let bad = { err: BASELINE_REJECT.format }
+    if (clientOpt === undefined) {
+        return {}
+    }
+    if (!isPlainObject(clientOpt)) {
+        return bad
+    }
+    let allow = woName === 'tokens' ? ['baseline', 'baselineSession'] : ['baseline']
+    let ks = Reflect.ownKeys(clientOpt)
+    if (ks.some((k) => allow.indexOf(k) < 0) || allow.some((k) => ks.indexOf(k) < 0)) {
+        return bad
+    }
+    let o = {}
+    for (let k of allow) {
+        let d = Object.getOwnPropertyDescriptor(clientOpt, k)
+        if (d === undefined || !('value' in d)) {
+            return bad
+        }
+        let v = copyBaseline(d.value)
+        if (v === null || !isBaselineValid(v)) {
+            return bad
+        }
+        o[k] = v
+    }
+    return o
+}
+
+
 //maxKeyBytes: 主鍵 UTF-8 位元組數上限, 同 LMDB 預設鍵長上限(lmdb/open.js 之 DEFAULT_MAX_KEY_SIZE; 實測 1978 位元組可寫、1979 即拒), 供清單儲存於寫入前驗證 (ADR-081)
 let maxKeyBytes = 1978
 
@@ -82,7 +162,13 @@ function timingSafePasswordEqual(a, b) {
 }
 
 
-function proc(woItems, procOrm, { srLog, srEmail, salt, minExpired, kpLang, passwordPolicy, allowUserRegistration, siteUrl, verifyBaseUrl }) {
+function proc(woItems, procOrm, { srLog, srEmail, salt, minExpired, kpLang, passwordPolicy, allowUserRegistration, siteUrl, verifyBaseUrl, withTabLocks, guardWrite }) {
+
+    //withTabLocks / guardWrite: 取自 w-serv-orm WServOrm 實例(每實例一個鎖管理器、每表一鍵, 規格 §7); 所有寫入 users / tokens / ips 之站點皆須在該表表鎖內執行 (R-CONC-01),
+    //且與 procProtect 共用同一組(同表只由同一鎖管理器寫入, 規格 §12). 缺少即無法保證互斥, 故不提供預設替身
+    if (!isfun(withTabLocks) || !isfun(guardWrite)) {
+        throw new Error('procCore needs withTabLocks and guardWrite from the WServOrm instance')
+    }
 
 
     //pmKeyMutex: per-key in-memory mutex, 同 key 序列化、不同 key 並行.
@@ -360,22 +446,24 @@ function proc(woItems, procOrm, { srLog, srEmail, salt, minExpired, kpLang, pass
         let userId = get(u, 'id', '')
         // console.log('userId', userId)
 
-        //createToken
-        let token = await createToken(userId)
+        //createToken, recheckUser: 驗密碼(CPU 密集)於鎖外, 鑄 token 時於 tokens 鎖內重讀使用者狀態 (R-CONC-01 W2-2):
+        //登入與停用 / 刪除 / 自動封鎖 / 重設密碼(皆於 [tokens, users] 鎖內撤銷 token)交錯時, 不致於撤銷之後才鑄出屬於已停用、已刪除、封鎖中或密碼已變更使用者之 token;
+        //verifiedUser 為鎖外通過驗證所依據之使用者, 鎖內以新鮮資料再判密碼未變、已驗證、未到期; withUser 令回傳 { token, user } 取鎖內新鮮之使用者, 登入回傳值由同一次有效狀態產生
+        let { token, user: uNow } = await createToken(userId, { recheckUser: true, verifiedUser: u, withUser: true })
         // console.log('token', token)
 
         //r
         let r = {
-            id: u.id,
-            account: u.account,
-            name: u.name,
-            email: u.email,
-            description: u.description,
-            from: u.from,
-            redir: u.redir,
-            isAdmin: u.isAdmin,
-            isActive: u.isActive,
-            isForceChangePw: u.isForceChangePw, //強制變更密碼旗標, 前端登入後判斷是否拉去 user view 強制變更
+            id: uNow.id,
+            account: uNow.account,
+            name: uNow.name,
+            email: uNow.email,
+            description: uNow.description,
+            from: uNow.from,
+            redir: uNow.redir,
+            isAdmin: uNow.isAdmin,
+            isActive: uNow.isActive,
+            isForceChangePw: uNow.isForceChangePw, //強制變更密碼旗標, 前端登入後判斷是否拉去 user view 強制變更
             token,
         }
 
@@ -384,7 +472,11 @@ function proc(woItems, procOrm, { srLog, srEmail, salt, minExpired, kpLang, pass
 
 
     //createToken
-    let createToken = async (userId) => {
+    //寫入於 tokens 表鎖內(S01); opt.recheckUser 為 true 時於鎖內重讀使用者, 已不存在、已停用或封鎖中即 reject 'failedLoginForCatch' (對外與密碼錯誤同回應, 不洩漏帳號狀態);
+    //另給 opt.verifiedUser(鎖外通過驗證所依據之使用者)時, 鎖內以新鮮資料再判登入條件: 密碼已變更 → 'failedLoginForCatch'、已不是已驗證 → 'userRegistrationNotVerified'、已到期 → 'loginAccountExpired',
+    //與鎖外同序同鍵; opt.withUser 為 true 時回傳 { token, user }(user 為鎖內新鮮之使用者, 僅 recheckUser 時有值), 否則回傳 token 字串
+    //userIdUpdate 記 token 擁有者(procOrm 以 userId 參數戳記, R-CONC-04)
+    let createToken = async (userId, opt = {}) => {
         let errTemp = null
 
         //check
@@ -407,13 +499,57 @@ function proc(woItems, procOrm, { srLog, srEmail, salt, minExpired, kpLang, pass
         //token
         let token = get(t, 'token', '')
 
-        //insert
-        await woItems.tokens.insert(t)
+        //insert, tokens 表鎖內
+        let rejectKey = null
+        let uFresh = null
+        await withTabLocks(['tokens'], async () => {
+
+            //recheckUser
+            if (get(opt, 'recheckUser') === true) {
+                let us = await woItems.users.select({ id: userId })
+                let u = get(us, 0, null)
+                let blocked = false
+                let timeBlocked = get(u, 'timeBlocked', '')
+                if (istimemsTZ(timeBlocked) && ot().format('YYYY-MM-DDTHH:mm:ss.SSSZ') <= timeBlocked) {
+                    blocked = true
+                }
+                if (size(us) !== 1 || get(u, 'isActive', '') === 'n' || blocked) {
+                    rejectKey = 'failedLoginForCatch'
+                    return
+                }
+
+                //verifiedUser: 鎖外通過驗證所依據之使用者; 登入條件以鎖內新鮮資料再判一次(與 loginByAccountAndPassword 同序同鍵)
+                let vu = get(opt, 'verifiedUser', null)
+                if (vu !== null) {
+                    if (get(u, 'password', '') !== get(vu, 'password', '')) {
+                        rejectKey = 'failedLoginForCatch' //等待期間密碼已被變更(如管理員重設): 先前以舊密碼通過之驗證不再有效
+                        return
+                    }
+                    if (!isestr(get(u, 'timeVerified', ''))) {
+                        rejectKey = 'userRegistrationNotVerified'
+                        return
+                    }
+                    let timeExpired = get(u, 'timeExpired', '')
+                    if (isestr(timeExpired) && istimemsTZ(timeExpired) && ot().format('YYYY-MM-DDTHH:mm:ss.SSSZ') > timeExpired) {
+                        rejectKey = 'loginAccountExpired'
+                        return
+                    }
+                }
+
+                uFresh = u
+            }
+
+            await procOrm(userId, 'tokens', 'insert', [t])
+
+        })
             .catch((err) => {
                 errTemp = err
             })
 
         //check
+        if (rejectKey !== null) {
+            return Promise.reject(rejectKey)
+        }
         if (errTemp) {
             console.log(errTemp)
             // console.log(`token`, token)
@@ -421,6 +557,9 @@ function proc(woItems, procOrm, { srLog, srEmail, salt, minExpired, kpLang, pass
             return Promise.reject(`can not create a token from userId`)
         }
 
+        if (get(opt, 'withUser') === true) {
+            return { token, user: uFresh }
+        }
         return token
     }
 
@@ -616,6 +755,7 @@ function proc(woItems, procOrm, { srLog, srEmail, salt, minExpired, kpLang, pass
 
 
     //refreshToken
+    //讀取、驗證與續期寫入皆在 tokens 表鎖內(S02): 讀到之 token 於寫入前不會被登出 / 撤銷插隊刪除, 且寫入為只改不增, 不致把已刪之 token 以殘缺列新增回庫 (X5)
     let refreshToken = async (token) => {
 
         //defense-in-depth NoSQL operator injection guard (reject key 名, 對齊 token 鏈統一 tokenExpired)
@@ -623,6 +763,13 @@ function proc(woItems, procOrm, { srLog, srEmail, salt, minExpired, kpLang, pass
             return Promise.reject('tokenExpired')
         }
 
+        return await withTabLocks(['tokens'], () => _refreshToken(token))
+    }
+
+
+    //_refreshToken, 須於 tokens 表鎖內呼叫
+    let _refreshToken = async (token) => {
+
         let errTemp = null
 
         //tks
@@ -677,15 +824,11 @@ function proc(woItems, procOrm, { srLog, srEmail, salt, minExpired, kpLang, pass
         let timeEndNew = ot().add(minExpired, 'minute').format('YYYY-MM-DDTHH:mm:ss.SSSZ')
         // console.log('timeEndNew', timeEndNew)
 
-        //timeUpdate
-        let timeUpdate = ot().format('YYYY-MM-DDTHH:mm:ss.SSSZ')
-
-        //save, 逐筆檢查(ADR-080): 單筆失敗時 ORM 仍 resolve, 不檢查即回報未生效之新到期時間
-        await ormWrite(woItems.tokens, 'save', {
+        //save, 經 procOrm 且 mustExist(只改不增, 列已不存在 → reject 'rowNotFound' 零寫入); procOrm 逐筆檢查(ADR-080)並戳記 timeUpdate / userIdUpdate(記 token 擁有者, R-CONC-04)
+        await procOrm(get(tk, 'userId', ''), 'tokens', 'save', [{
             id: tk.id,
             timeEnd: timeEndNew,
-            timeUpdate,
-        })
+        }], { mustExist: true })
             .catch((err) => {
                 errTemp = err
             })
@@ -704,6 +847,7 @@ function proc(woItems, procOrm, { srLog, srEmail, salt, minExpired, kpLang, pass
 
 
     //logoutByToken
+    //讀取與刪除在 tokens 表鎖內(S03); 刪除未命中回報既有鍵 'can not delete the token'
     let logoutByToken = async (token) => {
 
         //defense-in-depth NoSQL operator injection guard (reject key 名, 對齊 token 鏈統一 tokenExpired)
@@ -711,6 +855,13 @@ function proc(woItems, procOrm, { srLog, srEmail, salt, minExpired, kpLang, pass
             return Promise.reject('tokenExpired')
         }
 
+        return await withTabLocks(['tokens'], () => _logoutByToken(token))
+    }
+
+
+    //_logoutByToken, 須於 tokens 表鎖內呼叫
+    let _logoutByToken = async (token) => {
+
         let errTemp = null
 
         //tks
@@ -849,7 +1000,9 @@ function proc(woItems, procOrm, { srLog, srEmail, salt, minExpired, kpLang, pass
         let keyAccount = `createUser:account:${account}`
         let keyEmail = `createUser:email:${email}`
         let tokenVerify
-        await cst.setWithFree([keyAccount, keyEmail], async () => {
+        //唯一性檢查與 insert 於 users 表鎖內(S04, 修 X8): cst 之鍵空間與後台清單儲存(updateTabItems 取 users 表鎖)不同, 兩者原不互斥,
+        //自助註冊與管理員新增同帳號可同時成功; 取同一把表鎖後, 後到者必能讀到先到者所寫之列而被唯一性檢查擋下
+        await cst.setWithFree([keyAccount, keyEmail], () => withTabLocks(['users'], async () => {
 
             //check account unique (全域唯一，不限 isActive)
             let allUsers = await woItems.users.select()
@@ -890,7 +1043,7 @@ function proc(woItems, procOrm, { srLog, srEmail, salt, minExpired, kpLang, pass
                     srLog.error({ event: 'fun-createUser-insert', key: 'userRegistrationFailed', account, err: getErrorMessage(err) })
                     return Promise.reject('userRegistrationFailed')
                 })
-        })
+        }))
             .catch((err) => {
                 //remap setWithFree 之 'key in use' reject → 業務語意之 i18n 訊息.
                 //其他 reject (select unique check 之 'account/email already exists', insert 失敗之 userRegistrationFailed 等)
@@ -932,41 +1085,46 @@ function proc(woItems, procOrm, { srLog, srEmail, salt, minExpired, kpLang, pass
             return Promise.reject('verifyEmailInvalidToken')
         }
 
-        //以 tokenVerify 查找使用者
-        let us = await woItems.users.select({ tokenVerify: token })
-        if (size(us) === 0) {
-            return Promise.reject('verifyEmailInvalidToken')
-        }
-        let user = us[0]
+        //查找、檢查與寫入於 users 表鎖內(S05): timeVerified 為雙方欄位(後台可改、驗證信連結亦寫), 系統直寫須取表鎖, 後台持舊畫面存檔才會被偵測而拒收 (V4)
+        return await withTabLocks(['users'], async () => {
 
-        //check timeVerified (是否已驗證)
-        let timeVerified = get(user, 'timeVerified', '')
-        if (isestr(timeVerified)) {
-            return Promise.reject('verifyEmailAlreadyVerified')
-        }
+            //以 tokenVerify 查找使用者
+            let us = await woItems.users.select({ tokenVerify: token })
+            if (size(us) === 0) {
+                return Promise.reject('verifyEmailInvalidToken')
+            }
+            let user = us[0]
 
-        //update timeVerified: timemsTZ 格式(同其他時間欄與後台編輯之寫入). 原 now2str 為秒級, 共用判斷 getIsVerified(istimemsTZ)
-        //判為未驗證 → 後台清單顯示「未驗證」, 且該帳號設為管理者後過不了管理權限閘 funCheckAdmin (2026-09-29 修正)
-        //逐筆檢查(ADR-080): 寫入失敗回 verifyEmailFailed, 不顯示驗證成功; tokenVerify 未清, 使用者可再點同一連結重試
-        let errTemp = null
-        await ormWrite(woItems.users, 'save', {
-            id: user.id,
-            timeVerified: nowms2str(),
-            //F-053 fix (lazy clear): 不主動清 tokenVerify, 避免並發 resendVerifyEmail 寫的新 token
-            //被此處 race window 覆蓋. token 重用風險由 line ~818 之 isestr(timeVerified) → reject
-            //'verifyEmailAlreadyVerified' 擋住, 已驗證 user 點舊連結會得友善訊息.
-        })
-            .catch((err) => {
-                errTemp = err
-            })
+            //check timeVerified (是否已驗證)
+            let timeVerified = get(user, 'timeVerified', '')
+            if (isestr(timeVerified)) {
+                return Promise.reject('verifyEmailAlreadyVerified')
+            }
 
-        //check
-        if (errTemp !== null) {
-            srLog.error({ event: 'fun-verifyEmail-save', key: 'verifyEmailFailed', userId: user.id, err: getErrorMessage(errTemp) })
-            return Promise.reject('verifyEmailFailed')
-        }
+            //update timeVerified: timemsTZ 格式(同其他時間欄與後台編輯之寫入). 原 now2str 為秒級, 共用判斷 getIsVerified(istimemsTZ)
+            //判為未驗證 → 後台清單顯示「未驗證」, 且該帳號設為管理者後過不了管理權限閘 funCheckAdmin (2026-09-29 修正)
+            //經 procOrm 且 mustExist(只改不增, 列已不存在則拒絕而不新增殘缺列, X5), 更新者記該使用者本人 (R-CONC-04)
+            //逐筆檢查(ADR-080): 寫入失敗回 verifyEmailFailed, 不顯示驗證成功; tokenVerify 未清, 使用者可再點同一連結重試
+            let errTemp = null
+            await procOrm(user.id, 'users', 'save', [{
+                id: user.id,
+                timeVerified: nowms2str(),
+                //F-053 fix (lazy clear): 不主動清 tokenVerify, 避免並發 resendVerifyEmail 寫的新 token
+                //被此處 race window 覆蓋. token 重用風險由 line ~818 之 isestr(timeVerified) → reject
+                //'verifyEmailAlreadyVerified' 擋住, 已驗證 user 點舊連結會得友善訊息.
+            }], { mustExist: true })
+                .catch((err) => {
+                    errTemp = err
+                })
 
-        return { state: 'success', msg: 'ok' }
+            //check
+            if (errTemp !== null) {
+                srLog.error({ event: 'fun-verifyEmail-save', key: 'verifyEmailFailed', userId: user.id, err: getErrorMessage(errTemp) })
+                return Promise.reject('verifyEmailFailed')
+            }
+
+            return { state: 'success', msg: 'ok' }
+        })
     }
 
 
@@ -994,43 +1152,50 @@ function proc(woItems, procOrm, { srLog, srEmail, salt, minExpired, kpLang, pass
                 return Promise.reject('userRegistrationResendThrottled')
             }
 
-            //getGenUserByAccount
-            let u = null
-            try {
-                u = await _getGenUserByKV('account', account)
-            }
-            catch (err) {}
-            if (!u) {
-                return Promise.reject('userRegistrationResendInvalidEmail') //不洩露帳號是否存在
-            }
+            //查找、檢查與寫入於 users 表鎖內(S06; kmx 在外層、表鎖在內層): tokenVerify 雖屬伺服器專有欄位(規格 §4 不要求表鎖), 本套件統一取鎖並只改不增 (決策 D2),
+            //使讀到之列於寫入前不被刪除插隊而以殘缺列新增回庫 (X5)
+            let { userId, name, tokenVerify, errTemp } = await withTabLocks(['users'], async () => {
 
-            //check email match
-            let uEmail = get(u, 'email', '')
-            if (uEmail !== email) {
-                return Promise.reject('userRegistrationResendInvalidEmail')
-            }
+                //getGenUserByAccount
+                let u = null
+                try {
+                    u = await _getGenUserByKV('account', account)
+                }
+                catch (err) {}
+                if (!u) {
+                    return Promise.reject('userRegistrationResendInvalidEmail') //不洩露帳號是否存在
+                }
 
-            //check timeVerified
-            let timeVerified = get(u, 'timeVerified', '')
-            if (isestr(timeVerified)) {
-                return Promise.reject('userRegistrationAlreadyVerified')
-            }
+                //check email match
+                let uEmail = get(u, 'email', '')
+                if (uEmail !== email) {
+                    return Promise.reject('userRegistrationResendInvalidEmail')
+                }
 
-            //userId
-            let userId = get(u, 'id', '')
-            let name = get(u, 'name', '')
+                //check timeVerified
+                let timeVerified = get(u, 'timeVerified', '')
+                if (isestr(timeVerified)) {
+                    return Promise.reject('userRegistrationAlreadyVerified')
+                }
 
-            //產生新 tokenVerify 並更新至 users
-            //逐筆檢查(ADR-080): 寫入失敗即 reject, 不記節流、不寄出連結無效之信
-            let tokenVerify = `${genIDSeq()}`
-            let errTemp = null
-            await ormWrite(woItems.users, 'save', {
-                id: userId,
-                tokenVerify,
+                //userId
+                let userId = get(u, 'id', '')
+                let name = get(u, 'name', '')
+
+                //產生新 tokenVerify 並更新至 users, 更新者記該使用者 (R-CONC-04)
+                //逐筆檢查(ADR-080): 寫入失敗即 reject, 不記節流、不寄出連結無效之信
+                let tokenVerify = `${genIDSeq()}`
+                let errTemp = null
+                await procOrm(userId, 'users', 'save', [{
+                    id: userId,
+                    tokenVerify,
+                }], { mustExist: true })
+                    .catch((err) => {
+                        errTemp = err
+                    })
+
+                return { userId, name, tokenVerify, errTemp }
             })
-                .catch((err) => {
-                    errTemp = err
-                })
 
             //check
             if (errTemp !== null) {
@@ -1147,55 +1312,62 @@ function proc(woItems, procOrm, { srLog, srEmail, salt, minExpired, kpLang, pass
         //'incorrect old password' reject 路徑, 自然不會多寄信.
         return await kmx(`changeUserPassword:${userId}`, async () => {
 
-            //getGenUserByUserId (with password)
-            let u = await _getGenUserByKV('id', userId, { deletePassword: false })
+            //讀取、驗舊密碼與寫入於 users 表鎖內(S07; kmx 在外層、表鎖在內層): password 為伺服器專有欄位、isForceChangePw 為雙方欄位(系統直寫須取表鎖),
+            //驗證所依之 DB 雜湊與寫入間不被其他寫入者(重設密碼、後台存檔)插隊; 只改不增, 列已被刪則拒絕而不新增殘缺列 (X5)
+            let { u, email } = await withTabLocks(['users'], async () => {
 
-            //account
-            let account = get(u, 'account', '')
+                //getGenUserByUserId (with password)
+                let u = await _getGenUserByKV('id', userId, { deletePassword: false })
 
-            //check newPassword
-            let r = checkUserPassword(lang, newPassword, { account })
-            if (r.state === 'error') {
-                return Promise.reject(r.key)
-            }
+                //account
+                let account = get(u, 'account', '')
 
-            //passwordTrue
-            let passwordTrue = get(u, 'password', '')
+                //check newPassword
+                let r = checkUserPassword(lang, newPassword, { account })
+                if (r.state === 'error') {
+                    return Promise.reject(r.key)
+                }
 
-            //check (verifyPassword: 以明文舊密碼 + DB 自描述雜湊字串 + pepper(salt) 驗證)
-            if (!verifyPassword(oldPassword, passwordTrue, salt)) {
-                return Promise.reject('userChangePasswordIncorrectOld')
-            }
+                //passwordTrue
+                let passwordTrue = get(u, 'password', '')
 
-            //email
-            let email = get(u, 'email', '')
-            if (!isestr(email)) {
-                // console.log('token', token)
-                // console.log('u', u)
-                return Promise.reject('anUnexpectedErrorOccurred')
-            }
-            // console.log('email', email)
+                //check (verifyPassword: 以明文舊密碼 + DB 自描述雜湊字串 + pepper(salt) 驗證)
+                if (!verifyPassword(oldPassword, passwordTrue, salt)) {
+                    return Promise.reject('userChangePasswordIncorrectOld')
+                }
 
-            //hash newPassword
-            let passwordNew = hashPassword(newPassword, salt)
+                //email
+                let email = get(u, 'email', '')
+                if (!isestr(email)) {
+                    // console.log('token', token)
+                    // console.log('u', u)
+                    return Promise.reject('anUnexpectedErrorOccurred')
+                }
+                // console.log('email', email)
+
+                //hash newPassword
+                let passwordNew = hashPassword(newPassword, salt)
+
+                //save (清 isForceChangePw='n', 變更密碼成功後即解除強制變更), 更新者記該使用者本人 (R-CONC-04)
+                //逐筆檢查(ADR-080): 寫入失敗即 reject, 不寄「密碼已變更」信
+                let errTemp = null
+                await procOrm(userId, 'users', 'save', [{
+                    id: userId,
+                    password: passwordNew,
+                    isForceChangePw: 'n',
+                }], { mustExist: true })
+                    .catch((err) => {
+                        errTemp = err
+                    })
 
-            //save (清 isForceChangePw='n', 變更密碼成功後即解除強制變更)
-            //逐筆檢查(ADR-080): 寫入失敗即 reject, 不寄「密碼已變更」信
-            let errTemp = null
-            await ormWrite(woItems.users, 'save', {
-                id: userId,
-                password: passwordNew,
-                isForceChangePw: 'n',
-            })
-                .catch((err) => {
-                    errTemp = err
-                })
+                //check
+                if (errTemp !== null) {
+                    srLog.error({ event: 'fun-changePassword-save', key: 'userChangePasswordFail', userId, err: getErrorMessage(errTemp) })
+                    return Promise.reject('userChangePasswordFail')
+                }
 
-            //check
-            if (errTemp !== null) {
-                srLog.error({ event: 'fun-changePassword-save', key: 'userChangePasswordFail', userId, err: getErrorMessage(errTemp) })
-                return Promise.reject('userChangePasswordFail')
-            }
+                return { u, email }
+            })
 
             //若已變更密碼, 但寄送email失敗時, 不能報錯中斷流程
             try {
@@ -1296,43 +1468,50 @@ function proc(woItems, procOrm, { srLog, srEmail, salt, minExpired, kpLang, pass
                 return Promise.reject('adminResetPasswordAlreadyTriggered')
             }
 
-            //目標 user (含 password 拿到也不用, 只是確認存在)
-            let uTarget = null
-            try {
-                uTarget = await _getGenUserByKV('id', targetUserId, { deletePassword: true })
-            }
-            catch (err) {
-                return Promise.reject('adminResetPasswordUserNotFound')
-            }
-            if (!iseobj(uTarget)) {
-                return Promise.reject('adminResetPasswordUserNotFound')
-            }
+            //目標 user 查找與寫入於 users 表鎖內(S08; kmx 在外層、表鎖在內層): password 為伺服器專有欄位、isForceChangePw 為雙方欄位(系統直寫須取表鎖);
+            //只改不增, 目標已被刪則拒絕而不新增殘缺列 (X5); 更新者記操作管理員 (R-CONC-04)
+            let { targetAccount, targetName, targetEmail, newPassword } = await withTabLocks(['users'], async () => {
 
-            let targetAccount = get(uTarget, 'account', '')
-            let targetName = get(uTarget, 'name', 'unknow')
-            let targetEmail = get(uTarget, 'email', '')
+                //目標 user (含 password 拿到也不用, 只是確認存在)
+                let uTarget = null
+                try {
+                    uTarget = await _getGenUserByKV('id', targetUserId, { deletePassword: true })
+                }
+                catch (err) {
+                    return Promise.reject('adminResetPasswordUserNotFound')
+                }
+                if (!iseobj(uTarget)) {
+                    return Promise.reject('adminResetPasswordUserNotFound')
+                }
 
-            //產生隨機新密碼 (符合 passwordPolicy + account 限制)
-            let newPassword = genRandomPassword(passwordPolicy, targetAccount)
+                let targetAccount = get(uTarget, 'account', '')
+                let targetName = get(uTarget, 'name', 'unknow')
+                let targetEmail = get(uTarget, 'email', '')
+
+                //產生隨機新密碼 (符合 passwordPolicy + account 限制)
+                let newPassword = genRandomPassword(passwordPolicy, targetAccount)
+
+                //hash + save (含 isForceChangePw='y')
+                //逐筆檢查(ADR-080): 寫入失敗即 reject, 不記節流、不寄出未生效之新密碼
+                let hashed = hashPassword(newPassword, salt)
+                let errTemp = null
+                await procOrm(operatorId, 'users', 'save', [{
+                    id: targetUserId,
+                    password: hashed,
+                    isForceChangePw: 'y',
+                }], { mustExist: true })
+                    .catch((err) => {
+                        errTemp = err
+                    })
 
-            //hash + save (含 isForceChangePw='y')
-            //逐筆檢查(ADR-080): 寫入失敗即 reject, 不記節流、不寄出未生效之新密碼
-            let hashed = hashPassword(newPassword, salt)
-            let errTemp = null
-            await ormWrite(woItems.users, 'save', {
-                id: targetUserId,
-                password: hashed,
-                isForceChangePw: 'y',
-            })
-                .catch((err) => {
-                    errTemp = err
-                })
+                //check
+                if (errTemp !== null) {
+                    srLog.error({ event: 'fun-adminResetUserPassword-save', key: 'adminResetPasswordFailed', token: maskToken(token), targetUserId, err: getErrorMessage(errTemp) })
+                    return Promise.reject('adminResetPasswordFailed')
+                }
 
-            //check
-            if (errTemp !== null) {
-                srLog.error({ event: 'fun-adminResetUserPassword-save', key: 'adminResetPasswordFailed', token: maskToken(token), targetUserId, err: getErrorMessage(errTemp) })
-                return Promise.reject('adminResetPasswordFailed')
-            }
+                return { targetAccount, targetName, targetEmail, newPassword }
+            })
 
             //寫 throttle 時間戳 (放在 save 後, 確認此次 reset 已生效才記)
             lastResetTime.set(targetUserId, now)
@@ -1384,7 +1563,15 @@ function proc(woItems, procOrm, { srLog, srEmail, salt, minExpired, kpLang, pass
     //revokeTokensByUserId: 撤銷(刪除)使用者名下全部 token, 供刪除 / 停用使用者(updateTabItems)與登入失敗封鎖(procProtect.blockAccount)共用.
     //一次刪除該使用者全部 token 並逐筆檢查(ormWrite), 單筆失敗不中斷其餘筆, 有失敗即 reject 錯誤訊息(含失敗筆主鍵)供呼叫端記錄.
     //冪等(已無 token 時刪 0 筆), resolve 回傳刪除之 token 數. 使用者設計上不持有 isApp='y' token, 故一併撤 (ADR-037).
+    //S09: 對外之 revokeTokensByUserId 自取 tokens 表鎖; 上游已持 tokens 鎖者(updateTabItems users 路徑、procProtect 封鎖, 皆在 [tokens, users] 鎖內)
+    //須呼叫 revokeTokensByUserIdLocked(持鎖版), 不可重入 (規格 §7)
     let revokeTokensByUserId = async (userId) => {
+        return await withTabLocks(['tokens'], () => revokeTokensByUserIdLocked(userId))
+    }
+
+
+    //revokeTokensByUserIdLocked, 須於 tokens 表鎖內呼叫
+    let revokeTokensByUserIdLocked = async (userId) => {
 
         //check
         if (!isestr(userId)) {
@@ -1409,6 +1596,14 @@ function proc(woItems, procOrm, { srLog, srEmail, salt, minExpired, kpLang, pass
 
 
     //updateTabItems
+    //後台清單整表存檔(users / tokens / ips), 多人同時編輯之寫入契約 (原則 10; 規格 dspec/多人同時編輯之寫入契約.md; 規則帳本 rulebook_concurrency R-CONC-01~05):
+    //- 讀取、比對、驗證依賴庫內之項、diff、寫入、撤銷 token、清快取全程在該表表鎖內(users 為 [tokens, users], 因寫入後同鎖撤銷 token); 讀取為鎖內新鮮讀取(無 ORM 快取).
+    //- 帶基準(opt.optClient, 前端以 buildBaseline 對畫面所見之列自算): 與鎖內新鮮讀取比對, 不符整次拒收(零寫入, 先動先贏), 回語系鍵 saveStale / saveRowNotFound / saveBaselineFormat 提示重新載入.
+    //  刪除集合 = 基準內(且在範圍內) − 送出, 不刪載入後他人新增者; 修改 = 送出列之摘要 ≠ 基準, 只寫契約 fields(+ order), 伺服器專有欄位取庫內值, 摘要相同之列不寫(不戳記更新者).
+    //- 不帶基準(app 權杖直呼、已開啟之舊版頁面; 本 major 允許, 後者蓋前者, 下一 major 後台必帶): 仍取鎖、只改不增、伺服器專有欄位不採用客戶端值.
+    //  users / ips 刪除集合 = 庫內全部 − 送出(以外部為主); tokens 只處理應用系統金鑰列(isApp === 'y'), session 列不刪、不覆蓋、不復活.
+    //- tokens 採選項 P (R-CONC-03): app 列(契約 tokens)嚴格整表比對; session 列(契約 tokensSession)逐列寬鬆比對:
+    //  只比對管理員有修改或刪除之列; 載入後新增者不刪; 已不在庫內者不復活; 系統續期而管理員未動者不寫; 管理員有動且庫內已變者拒收.
     //分驗證與寫入兩階段 (ADR-080):
     //- 驗證階段: 全部驗證於任何寫入之前完成, 任一失敗即 reject 該驗證之 key, 資料庫無任何變更 (ADR-021).
     //  凡可於寫入前判定、寫入時才會被拒或被靜默改寫之輸入一律於此拒絕 (ADR-081): rows 非陣列、主鍵非字串 / 重複 / 超過鍵長上限 → 'invalidRows';
@@ -1419,6 +1614,13 @@ function proc(woItems, procOrm, { srLog, srEmail, salt, minExpired, kpLang, pass
     let updateTabItems = async (woName, rows, keyDetect, opt = {}) => {
         // console.log('updateTabItems', woName, rows.length, keyDetect)
 
+        //contract: 寫入契約(src/writeContracts, 前後端同一來源); tokens 另有 session 列契約
+        let contract = contracts[woName]
+        let contractSession = contracts.tokensSession
+        if (!iseobj(contract) || keyDetect !== contract.pk) {
+            throw new Error(`invalid woName[${woName}] or keyDetect[${keyDetect}] of updateTabItems`)
+        }
+
         //resetOrder
         let resetOrder = get(opt, 'resetOrder')
         if (!isbol(resetOrder)) {
@@ -1437,6 +1639,9 @@ function proc(woItems, procOrm, { srLog, srEmail, salt, minExpired, kpLang, pass
         //ocList: 該清單之讀取快取 (wsemi cache), 於寫入階段後清除 (ADR-008, ADR-080); 未給則不清
         let ocList = get(opt, 'ocList', null)
 
+        //optClient: 前端經 RPC 送入之第 4 參數(未驗證), 於下方 parseSaveOpt 驗證後自組基準; 不展開給 procOrm (規格 §6)
+        let optClient = get(opt, 'optClient')
+
         //check, rows 須為陣列 (ADR-081): 非陣列經 ltdtmapping 成空陣列, 比對時舊表全數歸為刪除
         if (!isarr(rows)) {
             return Promise.reject('invalidRows')
@@ -1444,11 +1649,16 @@ function proc(woItems, procOrm, { srLog, srEmail, salt, minExpired, kpLang, pass
 
         //idsNew: 前端標為新增(transient 欄位 _isNew === true)之列 id, 供下方比對既有列 (ADR-074);
         //_isNew 不在 schema keys 內, 下方 ltdtmapping 取欄時即剝除不入庫
+        //permsRaw: tokens 之 perms 於 ltdtmapping 前取原值(缺欄為 undefined), 供鎖內驗證 (ADR-069; ltdtmapping 會把缺欄補成 '')
         let idsNew = []
+        let permsRaw = new Map()
         each(rows, (r) => {
             if (get(r, '_isNew') === true) {
                 idsNew.push(get(r, 'id', ''))
             }
+            if (woName === 'tokens') {
+                permsRaw.set(get(r, 'id', ''), get(r, 'perms'))
+            }
         })
 
         //ltdtmapping
@@ -1508,223 +1718,428 @@ function proc(woItems, procOrm, { srLog, srEmail, salt, minExpired, kpLang, pass
             }
         }
 
-        //ltdtDiffByKey
-        let ltdtOld = await woItems[woName].select()
-        //console.log(`...woName[${woName}].select`)
-
-        //新增列已存在即拒絕 (ADR-074): 同一包重送且第 2 次於第 1 次完成後才處理時, 第 1 次已建立之列會被當「修改」,
-        //以前端之空值 / 佔位字覆寫伺服器於新增時填入之欄位(實測: 新使用者 timeVerified 被清空、建立者 / 建立時間寫成佔位字而無法登入)
-        if (size(idsNew) > 0) {
-            let kpIdOld = Object.create(null)
-            each(ltdtOld, (r) => {
-                kpIdOld[get(r, 'id', '')] = true
-            })
-            if (idsNew.some((id) => kpIdOld[id] === true)) {
-                return Promise.reject('saveNewRowExists')
-            }
-        }
-
-        //users 路徑: account 唯一性 + 非空驗證 (補 id/email 之外的 account; 防直打 API 寫入空/重複帳號).
-        //(a) 空值 → reject 'accountRequired'; (b) 本批內重複 或 與既有其他 user 之 account 衝突 → reject 'accountDuplicate'.
-        //帳號全域唯一, 與既有比對時排除「本批同 id 之自身既有列」(更新自己時 account 可維持不變).
-        if (woName === 'users') {
-            //既有 account → id 對照 (排除自身用)
-            let accountToIdOld = Object.create(null)
-            each(ltdtOld, (r) => {
-                let a = get(r, 'account', '')
-                if (isestr(a)) {
-                    accountToIdOld[a] = get(r, 'id', '')
-                }
-            })
-            let kpAccount = Object.create(null)
-            let errAccount = null
-            each(rows, (row) => {
-                let account = get(row, 'account', '')
-                let id = get(row, 'id', '')
-                //空值
-                if (!isestr(account)) {
-                    errAccount = 'accountRequired'
-                    return false //跳出
-                }
-                //本批內重複
-                if (haskey(kpAccount, account)) {
-                    errAccount = 'accountDuplicate'
-                    return false //跳出
-                }
-                //與既有其他 user (非自身) 衝突
-                if (haskey(accountToIdOld, account) && accountToIdOld[account] !== id) {
-                    errAccount = 'accountDuplicate'
-                    return false //跳出
-                }
-                kpAccount[account] = true
-            })
-            if (errAccount !== null) {
-                return Promise.reject(errAccount)
-            }
+        //parseSaveOpt: 驗證前端送入之基準(格式或版本不識 → baselineFormat, 不得降級為不帶基準); 於取鎖、讀庫之前
+        let po = parseSaveOpt(woName, optClient)
+        if (po.err !== undefined) {
+            return Promise.reject(kpSaveRejectKey[po.err])
         }
+        let isBased = po.baseline !== undefined
 
-        //users 路徑: 既有 row 的 password 保留 DB hash, 避免前端送來的 '' (getUsersList 已 strip)
-        //在儲存階段把 DB 既有 password 覆蓋成空字串, 等同把所有既有使用者密碼洗掉
-        if (woName === 'users') {
-            let oldById = Object.create(null)
-            each(ltdtOld, (r) => {
-                oldById[r.id] = r
-            })
+        //subRaw / subNorm: 送出之列(依 id); subRaw 為前端所見形式(供與基準比對摘要), subNorm 為寫入形式(tokens 之 perms 去重並依全集排序, ADR-069, 於鎖內驗證合法後才正規化)
+        let subRaw = new Map()
+        each(rows, (row) => {
+            subRaw.set(row.id, row)
+        })
+        let subNorm = subRaw
+        if (woName === 'tokens') {
+            subNorm = new Map()
             each(rows, (row) => {
-                let oldRow = oldById[row.id]
-                if (oldRow) {
-                    row.password = oldRow.password
-                }
+                subNorm.set(row.id, { ...row, perms: normAppPerms(permsRaw.get(row.id)) })
             })
         }
-
         let ltdtNew = rows
-        let r = ltdtDiffByKey(ltdtOld, ltdtNew, keyDetect)
-        // console.log('ltdtDiffByKey r', r)
-
-        //新增或修改列之任一欄位值(含主鍵; password 此時為明文、其後雜湊, 不檢查)會被 clearXSS 改寫即拒絕, 屬驗證階段 (ADR-021, ADR-081):
-        //procOrm 寫入時對各欄位 clearXSS(w-serv-orm getMapOrm 之 adjustData), 主鍵會被改寫者 1.1.8 起整批拒絕(屆時同批之刪除已落地),
-        //其餘欄位則被靜默改寫, 使儲存值與送入值不同(account / email 之唯一性與登入即以送入值比對).
-        //刪除不經 clearXSS、比對後屬 same 之列不寫入, 皆不檢查; 惟 users 以 resetOrder 依位置重編 order, 既有列只要位置變動即屬 diff 而受檢
-        let rowsMarkup = filter([...r.add, ...r.diff], (row) => {
-            return keys(row).some((k) => k !== 'password' && !isEqual(clearXSS(row[k]), row[k]))
-        })
-        if (size(rowsMarkup) > 0) {
-            return Promise.reject('htmlMarkupNotAllowed')
+        if (woName === 'tokens') {
+            ltdtNew = map(rows, (row) => subNorm.get(row.id))
         }
 
-        //users 路徑: 對新使用者的明文密碼進行 policy 檢查與 hash, 屬驗證階段, 須於任何寫入之前 (ADR-021, ADR-080;
-        //原置於刪除寫入之後, 密碼不符策略時刪除與撤銷已落地卻回驗證錯誤)
-        if (woName === 'users' && size(r.add) > 0) {
-            for (let row of r.add) {
-                let pw = get(row, 'password', '')
-                let account = get(row, 'account', '')
-                let chk = checkUserPassword(lang, pw, { account })
-                if (chk.state === 'error') {
-                    return Promise.reject(chk.key)
-                }
-                row.password = hashPassword(pw, salt)
-            }
-            //後台建帳自動填 timeVerified: timemsTZ 格式(見 verifyEmail 同處說明; 原 now2str 秒級使新建帳號顯示未驗證、設為管理者後過不了 funCheckAdmin, 2026-09-29 修正)
-            each(r.add, (row) => {
-                let tv = get(row, 'timeVerified', '')
-                if (!isestr(tv)) {
-                    row.timeVerified = nowms2str()
-                }
-            })
-        }
+        //表鎖: users 寫入後須同鎖撤銷其 token, 故為 [tokens, users] (withTabLocks 依表名碼元序取鎖, 不死結)
+        let tables = woName === 'users' ? ['tokens', 'users'] : [woName]
 
-        //rowsClear: 陣列欄變短之列先清空該欄: 儲存層 save 以 lodash merge 合併新舊列, 陣列逐索引合併, 新陣列較短時舊陣列尾端元素會殘留
-        //(如 tokens.perms 由 ['readTokens'] 撤銷為 [] 將無效, ADR-069). 先存 null 令該欄不再為陣列, 其後整列存入即為新陣列.
-        //兩次寫入之間該欄短暫為 null, tokens.perms 讀取端視同未設定(僅基本權限), 屬 fail closed 方向.
-        let rowsClear = []
-        if (size(r.diff) > 0) {
-            let kpOld = Object.create(null)
-            each(ltdtOld, (v) => {
-                kpOld[get(v, keyDetect, '')] = v
-            })
-            each(r.diff, (row) => {
-                let id = get(row, keyDetect, '')
-                let clear = null
-                each(row, (v, k) => {
-                    let vOld = get(kpOld, [id, k])
-                    if (isarr(v) && isarr(vOld) && v.length < vOld.length) {
-                        if (clear === null) {
-                            clear = { [keyDetect]: id }
+        //讀取 → 比對基準 → 驗證 → diff → 寫入 → 撤銷 → 清快取, 全在表鎖內(guardWrite: 取鎖 → 新鮮讀取 → compareBaseline → write); tokens 之 app 列嚴格整表比對於此, session 列寬鬆比對於 write 內
+        try {
+            await guardWrite({
+                tables,
+                read: () => woItems[woName].select(),
+                baseline: po.baseline, //undefined 為不帶基準(仍取鎖與讀取)
+                contract,
+                write: async (ltdtOld) => {
+                    //console.log(`...woName[${woName}].select`)
+
+                    //nowById: 鎖內新鮮讀取之列
+                    let nowById = new Map()
+                    each(ltdtOld, (r) => {
+                        nowById.set(get(r, 'id', ''), r)
+                    })
+
+                    //新增列已存在即拒絕 (ADR-074): 同一包重送且第 2 次於第 1 次完成後才處理時, 第 1 次已建立之列會被當「修改」,
+                    //以前端之空值 / 佔位字覆寫伺服器於新增時填入之欄位(實測: 新使用者 timeVerified 被清空、建立者 / 建立時間寫成佔位字而無法登入)
+                    if (size(idsNew) > 0 && idsNew.some((id) => nowById.has(id))) {
+                        return Promise.reject('saveNewRowExists')
+                    }
+
+                    //tokens 路徑: 清單存檔不得新增庫內不存在之 session 列(isApp 非 'y'; ADR-092), 不論帶不帶基準, 整次拒收(零寫入, 回固定語系鍵, 不回顯值):
+                    //session 權杖只由登入產生, 後台清單本就無新增 session 列之入口 (ADR-042); 不帶基準時無從分辨「新增」與「載入後已被登出 / 自動封鎖撤銷之舊列」,
+                    //送回舊列會使其復活而繞過撤銷. 例外: 帶基準而該列在 baselineSession 內者(載入時尚在, 其後被撤銷)不屬新增——管理員未動者下方略過、已動者拒收 saveStale.
+                    //應用系統金鑰列(isApp === 'y')新增、既有 session 列之刪除與升級為應用系統金鑰照舊.
+                    if (woName === 'tokens') {
+                        let idsBase = new Set(isBased ? [...po.baseline, ...po.baselineSession].map(([id]) => id) : [])
+                        let rowSessionNew = rows.find((r) => get(r, 'isApp', '') !== 'y' && !nowById.has(r.id) && !idsBase.has(r.id))
+                        if (rowSessionNew !== undefined) {
+                            srLog.warn({ event: 'fun-updateTabItems-reject', key: 'tokenSessionAddNotAllowed', woName })
+                            return Promise.reject('tokenSessionAddNotAllowed')
                         }
-                        clear[k] = null
                     }
-                })
-                if (clear !== null) {
-                    rowsClear.push(clear)
-                }
-            })
-        }
 
-        //寫入階段: 刪除 → 新增 → 修改, 任一步 reject 即停止後續步驟 (不回滾, ADR-044)
-        let errWrite = null
-        try {
+                    //users 路徑: account 唯一性 + 非空驗證 (補 id/email 之外的 account; 防直打 API 寫入空/重複帳號).
+                    //(a) 空值 → reject 'accountRequired'; (b) 本批內重複 或 與既有其他 user 之 account 衝突 → reject 'accountDuplicate'.
+                    //帳號全域唯一, 與既有比對時排除「本批同 id 之自身既有列」(更新自己時 account 可維持不變).
+                    if (woName === 'users') {
+                        //既有 account → id 對照 (排除自身用)
+                        let accountToIdOld = Object.create(null)
+                        each(ltdtOld, (r) => {
+                            let a = get(r, 'account', '')
+                            if (isestr(a)) {
+                                accountToIdOld[a] = get(r, 'id', '')
+                            }
+                        })
+                        let kpAccount = Object.create(null)
+                        let errAccount = null
+                        each(rows, (row) => {
+                            let account = get(row, 'account', '')
+                            let id = get(row, 'id', '')
+                            //空值
+                            if (!isestr(account)) {
+                                errAccount = 'accountRequired'
+                                return false //跳出
+                            }
+                            //本批內重複
+                            if (haskey(kpAccount, account)) {
+                                errAccount = 'accountDuplicate'
+                                return false //跳出
+                            }
+                            //與既有其他 user (非自身) 衝突
+                            if (haskey(accountToIdOld, account) && accountToIdOld[account] !== id) {
+                                errAccount = 'accountDuplicate'
+                                return false //跳出
+                            }
+                            kpAccount[account] = true
+                        })
+                        if (errAccount !== null) {
+                            return Promise.reject(errAccount)
+                        }
+                    }
 
-            //del
-            if (size(r.del) > 0) {
-                await procOrm(operatorId, woName, 'del', r.del) //operatorId 用於 audit (userIdUpdate)
-            }
+                    //tokens 路徑: 本批有變動(或新增)之列須為未設定或已登錄權限字串之陣列, 任一列不合法則整批 reject 不寫入 (ADR-069).
+                    //與 DB 相同之列不驗: DB 內既有之毀損值(非陣列等)若也擋, 後台整批存回將永遠失敗而無從修正; 其正規化後之有效權限與讀取端 fail closed 結果相同.
+                    //帶基準時, 摘要同基準(管理員未動)之列亦不驗 (外審 sol#5): 該列不會被寫入——app 列已由嚴格整表比對確認庫內即基準, session 列未動不寫——
+                    //如舊資料毀損值之 session 於載入後已被登出(庫內已無此列), 不得因此阻擋其他列之合法修改; 管理員有動或新增之列仍照驗
+                    if (woName === 'tokens') {
+                        let dgBase = new Map(isBased ? [...po.baseline, ...po.baselineSession] : [])
+                        for (let row of rows) {
+                            let perms = permsRaw.get(row.id)
+                            let old = nowById.get(row.id)
+                            if (old !== undefined && JSON.stringify(get(old, 'perms')) === JSON.stringify(perms)) {
+                                continue
+                            }
+                            if (dgBase.has(row.id) && dgBase.get(row.id) === digestRow(subRaw.get(row.id), contract)) {
+                                continue
+                            }
+                            if (!isAppPermsValue(perms)) {
+                                return Promise.reject('tokenPermsInvalid')
+                            }
+                        }
+                    }
+
+                    //dels / adds / mods: 刪除(庫內之列)、新增(送出之列)、修改(送出之列)
+                    let dels = []
+                    let adds = []
+                    let mods = []
+                    let isApp = (r) => get(r, 'isApp', '') === 'y'
+
+                    if (woName === 'tokens' && isBased) {
+
+                        //app 列已由 guardWrite 嚴格整表比對相符(增、刪、改皆無差異); session 列(契約 tokensSession)逐列寬鬆比對,
+                        //只取 compareBaseline 之 changed(庫內摘要與基準不同者, 如續期改 timeEnd); added(載入後新增者)忽略; removed(已不在庫內者)以 nowById 判斷
+                        let baseA = new Map(po.baseline)
+                        let baseS = new Map(po.baselineSession)
+                        let cs = compareBaseline(ltdtOld, po.baselineSession, contractSession)
+                        let changedS = new Set(cs.ok ? [] : cs.changed)
+
+                        //app 列: 基準內未送出 → 刪除; 送出之摘要 ≠ 基準 → 修改
+                        for (let [id, dg] of baseA) {
+                            let sub = subRaw.get(id)
+                            if (sub === undefined) {
+                                dels.push(nowById.get(id))
+                            }
+                            else if (digestRow(sub, contract) !== dg) {
+                                mods.push(subNorm.get(id))
+                            }
+                        }
 
-            //add
-            if (size(r.add) > 0) {
-                if (woName === 'tokens') {
-                    //tokens 之 userId 為令牌擁有者, 而 procOrm(w-serv-orm getMapOrm 之 adjustData)於 insert 時把 userId 欄改寫為其 userId 參數(視為建立者):
-                    //依擁有者分組並以擁有者為參數寫入, 使擁有者即送入值(原以本清單之操作者 '' 寫入, 鑄造之金鑰無擁有者而不可用; ADR-042, ADR-084).
-                    //分組用 Map: 擁有者為任意字串, 一般物件會誤中原型鏈上之鍵(如 constructor)
-                    let mpOwner = new Map()
-                    each(r.add, (row) => {
-                        let owner = get(row, 'userId', '')
-                        if (!mpOwner.has(owner)) {
-                            mpOwner.set(owner, [])
+                        //session 列
+                        for (let [id, dg] of baseS) {
+                            let sub = subRaw.get(id)
+                            let now = nowById.get(id)
+                            let live = now !== undefined && contractSession.scope(now)
+                            if (sub === undefined) {
+                                //管理員刪除: 已不在庫內(已被登出 / 撤銷)則冪等略過; 在庫內而庫內已變(如已續期)→ 管理員有動且庫內已變, 拒收
+                                if (!live) {
+                                    continue
+                                }
+                                if (changedS.has(id)) {
+                                    return Promise.reject('saveStale')
+                                }
+                                dels.push(now)
+                                continue
+                            }
+                            //管理員未動(摘要同基準): 不寫, 系統續期之 timeEnd 不被舊值蓋回, 已撤銷者不復活 (X1, X7)
+                            if (digestRow(sub, contract) === dg) {
+                                continue
+                            }
+                            //管理員有動: 已不在庫內或庫內已變 → 拒收; 否則修改(含升級為應用系統金鑰)
+                            if (!live || changedS.has(id)) {
+                                return Promise.reject('saveStale')
+                            }
+                            mods.push(subNorm.get(id))
                         }
-                        mpOwner.get(owner).push(row)
+
+                        //基準之外之列(管理員新增): 已存在於庫內(他人載入後新增而撞 id)→ 拒收; 否則新增
+                        for (let [id] of subRaw) {
+                            if (baseA.has(id) || baseS.has(id)) {
+                                continue
+                            }
+                            if (nowById.has(id)) {
+                                return Promise.reject('saveStale')
+                            }
+                            adds.push(subNorm.get(id))
+                        }
+
+                    }
+                    else if (woName === 'tokens') {
+
+                        //不帶基準(app 權杖直呼、已開啟之舊版頁面): 刪除與修改只處理應用系統金鑰列(庫內 isApp === 'y',
+                        //修改另含送出 isApp === 'y' 者, 即升級為應用系統金鑰); session 列(登入新增、續期改 timeEnd、登出或封鎖刪除, 系統頻繁增刪)
+                        //不刪、不以送入值覆蓋, 載入後才登入之 session 因而不被誤刪 (E1, D3). 新增列(送出而庫內無此 id)照常新增,
+                        //含直打 API 鑄造使用者 token 與應用系統金鑰(ADR-042, ADR-084); 此路徑無基準可辨是否為已被撤銷之 session, 該風險由帶基準之後台頁(X1)承擔防護
+                        each(ltdtOld, (r) => {
+                            if (isApp(r) && !subRaw.has(r.id)) {
+                                dels.push(r)
+                            }
+                        })
+                        for (let [id, sub] of subNorm) {
+                            let old = nowById.get(id)
+                            if (old === undefined) {
+                                adds.push(sub)
+                                continue
+                            }
+                            if (!isApp(old) && !isApp(sub)) {
+                                continue
+                            }
+                            //以正規化後之列(perms 去重排序,缺欄 / 毀損值變 [])比對庫內: DB 既有之毀損值與無 perms 欄之舊列於存回時正規化為空陣列(ADR-069, PERM-A-005),
+                            //此為既有且有意之行為, 不以送入原值比對(外審 sol#8 之『原樣重送零寫入』與之衝突, 不採)
+                            if (digestRow(sub, contract) !== digestRow(old, contract)) {
+                                mods.push(sub)
+                            }
+                        }
+
+                    }
+                    else {
+
+                        //users / ips: 帶基準時 guardWrite 已嚴格比對相符(庫內 = 基準), 刪除集合 = 基準內 − 送出; 不帶基準時 = 庫內全部 − 送出
+                        if (isBased) {
+                            for (let [id] of po.baseline) {
+                                if (!subRaw.has(id) && nowById.has(id)) {
+                                    dels.push(nowById.get(id))
+                                }
+                            }
+                        }
+                        else {
+                            each(ltdtOld, (r) => {
+                                if (!subRaw.has(r.id)) {
+                                    dels.push(r)
+                                }
+                            })
+                        }
+                        //修改 = 送出列之摘要(契約 fields)≠ 庫內; 名次欄(users.order)值不同亦寫(存檔依列序重編)
+                        each(rows, (sub) => {
+                            let old = nowById.get(sub.id)
+                            if (old === undefined) {
+                                adds.push(sub)
+                                return
+                            }
+                            let changed = digestRow(sub, contract) !== digestRow(old, contract)
+                            if (!changed && contract.orderKey) {
+                                changed = !isEqual(get(old, contract.orderKey), get(sub, contract.orderKey))
+                            }
+                            if (changed) {
+                                mods.push(sub)
+                            }
+                        })
+
+                    }
+
+                    //rowsAdd: 新增列保留全欄形狀, 伺服器專有欄位(含稽核欄)不採用客戶端值, 由 procOrm 戳記或留空; users 之 password 為新增列例外(明文, 其後檢查策略並雜湊)
+                    let rowsAdd = map(adds, (sub) => {
+                        let row = { ...sub }
+                        each(contract.serverOnly, (k) => {
+                            row[k] = ''
+                        })
+                        if (woName === 'users') {
+                            row.password = get(sub, 'password', '')
+                        }
+                        return row
+                    })
+
+                    //rowsMod: 修改列只寫契約 fields(+ 名次欄); 伺服器專有欄位(password、tokenVerify、稽核欄)取庫內值, 不入寫入列 (X2)
+                    let rowsMod = map(mods, (sub) => {
+                        let row = pickWriteRow(sub, contract)
+                        if (contract.orderKey) {
+                            row[contract.orderKey] = sub[contract.orderKey]
+                        }
+                        return row
+                    })
+
+                    //新增或修改列之任一欄位值(含主鍵; password 此時為明文、其後雜湊, 不檢查)會被 clearXSS 改寫即拒絕, 屬驗證階段 (ADR-021, ADR-081):
+                    //procOrm 寫入時對各欄位 clearXSS(w-serv-orm getMapOrm 之 adjustData), 主鍵會被改寫者 1.1.8 起整批拒絕(屆時同批之刪除已落地),
+                    //其餘欄位則被靜默改寫, 使儲存值與送入值不同(account / email 之唯一性與登入即以送入值比對).
+                    //刪除不經 clearXSS、摘要相同之列不寫入, 皆不檢查; 惟 users 以 resetOrder 依位置重編 order, 既有列只要位置變動即屬修改而受檢
+                    let rowsMarkup = filter([...rowsAdd, ...rowsMod], (row) => {
+                        return keys(row).some((k) => k !== 'password' && !isEqual(clearXSS(row[k]), row[k]))
                     })
-                    for (let [owner, rowsOwner] of mpOwner) {
-                        await procOrm(owner, woName, 'insert', rowsOwner)
+                    if (size(rowsMarkup) > 0) {
+                        return Promise.reject('htmlMarkupNotAllowed')
                     }
-                }
-                else {
-                    await procOrm(operatorId, woName, 'insert', r.add)
-                }
-            }
 
-            //diff
-            if (size(rowsClear) > 0) {
-                await procOrm(operatorId, woName, 'save', rowsClear)
-            }
-            if (size(r.diff) > 0) {
-                await procOrm(operatorId, woName, 'save', r.diff)
-            }
+                    //users 路徑: 對新使用者的明文密碼進行 policy 檢查與 hash, 屬驗證階段, 須於任何寫入之前 (ADR-021, ADR-080;
+                    //原置於刪除寫入之後, 密碼不符策略時刪除與撤銷已落地卻回驗證錯誤)
+                    if (woName === 'users' && size(rowsAdd) > 0) {
+                        for (let row of rowsAdd) {
+                            let pw = get(row, 'password', '')
+                            let account = get(row, 'account', '')
+                            let chk = checkUserPassword(lang, pw, { account })
+                            if (chk.state === 'error') {
+                                return Promise.reject(chk.key)
+                            }
+                            row.password = hashPassword(pw, salt)
+                        }
+                        //後台建帳自動填 timeVerified: timemsTZ 格式(見 verifyEmail 同處說明; 原 now2str 秒級使新建帳號顯示未驗證、設為管理者後過不了 funCheckAdmin, 2026-09-29 修正)
+                        each(rowsAdd, (row) => {
+                            let tv = get(row, 'timeVerified', '')
+                            if (!isestr(tv)) {
+                                row.timeVerified = nowms2str()
+                            }
+                        })
+                    }
+
+                    //rowsClear: 陣列欄變短之列先清空該欄: 儲存層 save 以 lodash merge 合併新舊列, 陣列逐索引合併, 新陣列較短時舊陣列尾端元素會殘留
+                    //(如 tokens.perms 由 ['readTokens'] 撤銷為 [] 將無效, ADR-069). 先存 null 令該欄不再為陣列, 其後整列存入即為新陣列.
+                    //兩次寫入之間該欄短暫為 null, tokens.perms 讀取端視同未設定(僅基本權限), 屬 fail closed 方向.
+                    let rowsClear = []
+                    each(rowsMod, (row) => {
+                        let id = get(row, keyDetect, '')
+                        let clear = null
+                        each(row, (v, k) => {
+                            let vOld = get(nowById.get(id), k)
+                            if (isarr(v) && isarr(vOld) && v.length < vOld.length) {
+                                if (clear === null) {
+                                    clear = { [keyDetect]: id }
+                                }
+                                clear[k] = null
+                            }
+                        })
+                        if (clear !== null) {
+                            rowsClear.push(clear)
+                        }
+                    })
+
+                    //寫入階段: 刪除 → 新增 → 修改, 任一步 reject 即停止後續步驟 (不回滾, ADR-044); 同一表鎖內, 刪除與修改皆 mustExist(只改不增, 列已不存在 → rowNotFound 而不新增殘缺列)
+                    let errWrite = null
+                    try {
+
+                        //del, operatorId 用於 audit (userIdUpdate)
+                        if (size(dels) > 0) {
+                            await procOrm(operatorId, woName, 'del', map(dels, (row) => ({ id: row.id })), { mustExist: true })
+                        }
+
+                        //add
+                        if (size(rowsAdd) > 0) {
+                            if (woName === 'tokens') {
+                                //tokens 之 userId 為令牌擁有者(非建立者): keepUserId 保留列上非空之擁有者, userIdUpdate 記操作者 (ADR-042, ADR-084; w-serv-orm 1.1.17);
+                                //擁有者為空者以操作者補, 不再寫成無擁有者之金鑰
+                                await procOrm(operatorId, woName, 'insert', rowsAdd, { keepUserId: true })
+                            }
+                            else {
+                                await procOrm(operatorId, woName, 'insert', rowsAdd)
+                            }
+                        }
 
+                        //mod
+                        if (size(rowsClear) > 0) {
+                            await procOrm(operatorId, woName, 'save', rowsClear, { mustExist: true })
+                        }
+                        if (size(rowsMod) > 0) {
+                            await procOrm(operatorId, woName, 'save', rowsMod, { mustExist: true })
+                        }
+
+                    }
+                    catch (err) {
+                        errWrite = err
+                    }
+
+                    //users 路徑: 撤銷本批欲刪除與欲停用(isActive==='n')者名下全部 token, 避免 orphan token 仍可 checkToken/refreshToken 續命 (ADR-037).
+                    //撤銷範圍依本批意圖, 不依寫入成敗(寫入失敗之列亦撤, fail closed); 先寫入再撤銷: 刪除 / 停用落地後已無法登入, 不會再產生新 token.
+                    //停用者沿用整表掃描(本批表內 isActive==='n' 者皆撤, 冪等). 撤銷失敗僅 srLog.error 不阻斷主流程.
+                    //與寫入同在 [tokens, users] 鎖內, 故用持鎖版 revokeTokensByUserIdLocked (不可重入, R-CONC-01)
+                    if (woName === 'users') {
+                        for (let row of dels) {
+                            let userId = get(row, 'id', '')
+                            await revokeTokensByUserIdLocked(userId)
+                                .catch((err) => {
+                                    srLog.error({ event: 'fun-updateTabItems-revokeTokenOnDelete', userId, err: getErrorMessage(err) })
+                                })
+                        }
+                        for (let row of rows) {
+                            if (get(row, 'isActive', '') !== 'n') {
+                                continue
+                            }
+                            let userId = get(row, 'id', '')
+                            await revokeTokensByUserIdLocked(userId)
+                                .catch((err) => {
+                                    srLog.error({ event: 'fun-updateTabItems-revokeTokenOnDisable', userId, err: getErrorMessage(err) })
+                                })
+                        }
+                    }
+
+                    //寫入後立即 invalidate 30s cache, 避免改完之統計頁顯示舊資料 (ADR-008, audit F-050); 寫入失敗時資料庫可能已部分變更, 一併清除 (ADR-080)
+                    if (ocList !== null) {
+                        ocList.clear('fun')
+                    }
+
+                    //check, 寫入階段失敗一律回 saveWriteFail, procOrm 原文(含失敗筆主鍵)僅記 log (ADR-034, ADR-080)
+                    if (errWrite !== null) {
+                        srLog.error({ event: 'fun-updateTabItems-write', key: 'saveWriteFail', woName, err: getErrorMessage(errWrite) })
+                        return Promise.reject('saveWriteFail')
+                    }
+
+                },
+            })
         }
         catch (err) {
-            errWrite = err
-        }
 
-        //users 路徑: 撤銷本批欲刪除與欲停用(isActive==='n')者名下全部 token, 避免 orphan token 仍可 checkToken/refreshToken 續命 (ADR-037).
-        //撤銷範圍依本批意圖, 不依寫入成敗(寫入失敗之列亦撤, fail closed); 先寫入再撤銷: 刪除 / 停用落地後已無法登入, 不會再產生新 token.
-        //停用者沿用整表掃描(本批表內 isActive==='n' 者皆撤, 冪等). 撤銷失敗僅 srLog.error 不阻斷主流程.
-        if (woName === 'users') {
-            for (let row of r.del) {
-                let userId = get(row, 'id', '')
-                await revokeTokensByUserId(userId)
-                    .catch((err) => {
-                        srLog.error({ event: 'fun-updateTabItems-revokeTokenOnDelete', userId, err: getErrorMessage(err) })
-                    })
-            }
-            for (let row of ltdtNew) {
-                if (get(row, 'isActive', '') !== 'n') {
-                    continue
+            //契約拒收鍵(baselineMismatch / rowNotFound / baselineFormat)轉語系鍵, 提示重新載入; 取鍵一律用核心 getRejectKey
+            let kSave = getSaveRejectKey(err)
+            if (kSave !== null) {
+                if (srLog && isfun(srLog.warn)) {
+                    srLog.warn({ event: 'fun-updateTabItems-reject', key: kSave, woName }) //原則 3: 後端錯誤 log error key
                 }
-                let userId = get(row, 'id', '')
-                await revokeTokensByUserId(userId)
-                    .catch((err) => {
-                        srLog.error({ event: 'fun-updateTabItems-revokeTokenOnDisable', userId, err: getErrorMessage(err) })
-                    })
+                return Promise.reject(kSave)
             }
-        }
 
-        //寫入後立即 invalidate 30s cache, 避免改完之統計頁顯示舊資料 (ADR-008, audit F-050); 寫入失敗時資料庫可能已部分變更, 一併清除 (ADR-080)
-        if (ocList !== null) {
-            ocList.clear('fun')
-        }
+            //rowsInvalid: 庫內讀出之列主鍵重複或缺漏, 屬伺服端資料錯誤(重新載入無法解決), 記 log 後回伺服端錯誤鍵
+            if (getRejectKey(err) === 'rowsInvalid') {
+                srLog.error({ event: 'fun-updateTabItems-rowsInvalid', key: 'anUnexpectedErrorOccurred', woName, err: getErrorMessage(err) })
+                return Promise.reject('anUnexpectedErrorOccurred')
+            }
 
-        //check, 寫入階段失敗一律回 saveWriteFail, procOrm 原文(含失敗筆主鍵)僅記 log (ADR-034, ADR-080)
-        if (errWrite !== null) {
-            srLog.error({ event: 'fun-updateTabItems-write', key: 'saveWriteFail', woName, err: getErrorMessage(errWrite) })
-            return Promise.reject('saveWriteFail')
+            return Promise.reject(err)
         }
 
-        //users 路徑: 回傳前剝除 password 欄位, 避免明文/hash 經 API 洩漏
+        //users 路徑: 回傳前剝除 password 與 tokenVerify 欄位, 避免明文/hash/驗證 token 經 API 洩漏
         if (woName === 'users') {
             ltdtNew = map(ltdtNew, (row) => {
                 let copy = { ...row }
                 delete copy.password
+                delete copy.tokenVerify
                 return copy
             })
         }
@@ -1938,9 +2353,11 @@ function proc(woItems, procOrm, { srLog, srEmail, salt, minExpired, kpLang, pass
         //console.log(`...users.select`)
 
         //delete password, 無錯誤取得後即先刪除, 避免調整程式時意外洩漏hash後密碼
+        //tokenVerify (註冊驗證用 token, 憑證類) 同步收回 (T3, 原則 8): 契約生效後後台不再需要整列存回它 (伺服器專有欄位, 存檔不採用客戶端值, R-CONC-02)
         if (deletePassword) {
             us = map(us, (u) => {
                 delete u.password
+                delete u.tokenVerify
                 return u
             })
         }
@@ -2001,7 +2418,8 @@ function proc(woItems, procOrm, { srLog, srEmail, salt, minExpired, kpLang, pass
 
 
     //checkTokenAndUpdateUsersList
-    let checkTokenAndUpdateUsersList = async (token, lang, rows, opt = {}) => {
+    //optClient: 前端經 RPC 送入之第 4 參數 { baseline }(未驗證, 由 updateTabItems 內 parseSaveOpt 驗證; 不展開給 procOrm); 未給即不帶基準
+    let checkTokenAndUpdateUsersList = async (token, lang, rows, opt = {}, optClient = undefined) => {
 
         //checkToken
         await checkToken(token, opt) //resolve僅回傳true, reject代表無效token或檢測token發生錯誤
@@ -2053,7 +2471,7 @@ function proc(woItems, procOrm, { srLog, srEmail, salt, minExpired, kpLang, pass
 
             //updateUsersList (帶 lang/operatorId 給下層用於 add 群組密碼策略檢查與 audit)
             //停用使用者即時撤銷其全部 token (ADR-037) 與清除使用者清單快取 (ADR-008), 皆於 updateTabItems 寫入階段後執行, 不論寫入成敗 (ADR-080)
-            rows = await updateUsersList(rows, { lang, operatorId })
+            rows = await updateUsersList(rows, { lang, operatorId, optClient })
 
             return rows
         })
@@ -2098,43 +2516,30 @@ function proc(woItems, procOrm, { srLog, srEmail, salt, minExpired, kpLang, pass
 
 
     //updateTokensList
-    let updateTokensList = async (rows) => {
+    //opt: { operatorId, optClient }, operatorId 為操作者 id(稽核 userIdUpdate, R-CONC-04), optClient 見 checkTokenAndUpdateUsersList
+    let updateTokensList = async (rows, opt = {}) => {
 
         //rows 來自使用端, 須為陣列才可走訪 (同 checkTokenAndUpdateUsersList; 非陣列〔如帶 length 之物件〕原於下方 for…of 拋 TypeError, R-OBJ-ITER-01)
         if (!isarr(rows)) {
             return Promise.reject('invalidRows')
         }
 
-        //perms: 本批有變動(或新增)之列須為未設定或已登錄權限字串之陣列, 任一列不合法則整批 reject 不寫入 (ADR-069).
-        //與 DB 相同之列不驗: DB 內既有之毀損值(非陣列等)若也擋, 後台整批存回將永遠失敗而無從修正; 其正規化後之有效權限與讀取端 fail closed 結果相同.
-        let kpPermsOld = Object.create(null)
-        each(await woItems.tokens.select(), (t) => {
-            kpPermsOld[t.id] = JSON.stringify(get(t, 'perms'))
-        })
-        for (let r of rows) {
-            let perms = get(r, 'perms')
-            let id = get(r, 'id', '')
-            if (haskey(kpPermsOld, id) && kpPermsOld[id] === JSON.stringify(perms)) {
-                continue
-            }
-            if (!isAppPermsValue(perms)) {
-                return Promise.reject('tokenPermsInvalid')
-            }
-        }
-        //合法者去重並依全集排序後儲存
-        rows = map(rows, (r) => {
-            return { ...r, perms: normAppPerms(get(r, 'perms')) }
-        })
-
+        //perms 之驗證(本批有變動或新增之列須為未設定或已登錄權限字串之陣列, 任一列不合法則整批 reject 不寫入, ADR-069)與合法者去重並依全集排序,
+        //須對照鎖內新鮮讀取之庫內值, 故移入 updateTabItems 之表鎖內(原於鎖外讀庫比對, 與寫入之間可被插隊)
         //updateTabItems, 清除權杖清單快取於其寫入階段後執行 (ADR-080)
-        rows = await updateTabItems('tokens', rows, 'id', { resetOrder: false, ocList: ocGetTokensList })
+        rows = await updateTabItems('tokens', rows, 'id', {
+            resetOrder: false,
+            operatorId: get(opt, 'operatorId', ''),
+            optClient: get(opt, 'optClient'),
+            ocList: ocGetTokensList,
+        })
 
         return rows
     }
 
 
     //checkTokenAndUpdateTokensList
-    let checkTokenAndUpdateTokensList = async (token, rows, opt = {}) => {
+    let checkTokenAndUpdateTokensList = async (token, rows, opt = {}, optClient = undefined) => {
 
         //checkToken
         await checkToken(token, opt) //resolve僅回傳true, reject代表無效token或檢測token發生錯誤
@@ -2147,7 +2552,7 @@ function proc(woItems, procOrm, { srLog, srEmail, salt, minExpired, kpLang, pass
         return await lockSave('updateTokensList', operatorId, async () => {
 
             //updateTokensList, 清除權杖清單快取 (ADR-008) 於 updateTabItems 寫入階段後執行, 不論寫入成敗 (ADR-080)
-            rows = await updateTokensList(rows)
+            rows = await updateTokensList(rows, { operatorId, optClient })
 
             return rows
         })
@@ -2187,17 +2592,23 @@ function proc(woItems, procOrm, { srLog, srEmail, salt, minExpired, kpLang, pass
 
 
     //updateIpsList
-    let updateIpsList = async (rows) => {
+    //opt: { operatorId, optClient }, 同 updateTokensList
+    let updateIpsList = async (rows, opt = {}) => {
 
         //updateTabItems, 清除 IP 清單快取於其寫入階段後執行 (ADR-080)
-        rows = await updateTabItems('ips', rows, 'id', { resetOrder: false, ocList: ocGetIpsList })
+        rows = await updateTabItems('ips', rows, 'id', {
+            resetOrder: false,
+            operatorId: get(opt, 'operatorId', ''),
+            optClient: get(opt, 'optClient'),
+            ocList: ocGetIpsList,
+        })
 
         return rows
     }
 
 
     //checkTokenAndUpdateIpsList
-    let checkTokenAndUpdateIpsList = async (token, rows, opt = {}) => {
+    let checkTokenAndUpdateIpsList = async (token, rows, opt = {}, optClient = undefined) => {
 
         //checkToken
         await checkToken(token, opt) //resolve僅回傳true, reject代表無效token或檢測token發生錯誤
@@ -2210,7 +2621,7 @@ function proc(woItems, procOrm, { srLog, srEmail, salt, minExpired, kpLang, pass
         return await lockSave('updateIpsList', operatorId, async () => {
 
             //updateIpsList, 清除 IP 清單快取 (ADR-008) 於 updateTabItems 寫入階段後執行, 不論寫入成敗 (ADR-080)
-            rows = await updateIpsList(rows)
+            rows = await updateIpsList(rows, { operatorId, optClient })
 
             return rows
         })
@@ -2256,6 +2667,7 @@ function proc(woItems, procOrm, { srLog, srEmail, salt, minExpired, kpLang, pass
         getIpByKV,
 
         revokeTokensByUserId,
+        revokeTokensByUserIdLocked, //持鎖版: 呼叫端須已持有 tokens 表鎖(procProtect 封鎖於 [tokens, users] 鎖內使用), 不可重入
 
         getGenUserByKV,
         getGenUserByUserId,