w-web-perm 1.1.4 → 1.1.6

package/docs/index.html

@@ -29,7 +29,7 @@
 <nav >
     
     
-    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WWebPerm.html">WWebPerm</a></li></ul><h3>Global</h3><ul><li><a href="global.html#fetchJson">fetchJson</a></li><li><a href="global.html#mergePickKeysOnly">mergePickKeysOnly</a></li></ul>
+    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WWebPerm.html">WWebPerm</a></li></ul><h3>Global</h3><ul><li><a href="global.html#createLegendMeasurer">createLegendMeasurer</a></li><li><a href="global.html#createLockSave">createLockSave</a></li><li><a href="global.html#decideLegendType">decideLegendType</a></li><li><a href="global.html#describeUpstream">describeUpstream</a></li><li><a href="global.html#fetchJson">fetchJson</a></li><li><a href="global.html#genLegend">genLegend</a></li><li><a href="global.html#maskQuery">maskQuery</a></li><li><a href="global.html#maskTok">maskTok</a></li><li><a href="global.html#maskUrl">maskUrl</a></li><li><a href="global.html#mergePickKeysOnly">mergePickKeysOnly</a></li><li><a href="global.html#reuseDeletedIds">reuseDeletedIds</a></li><li><a href="global.html#submitGuard">submitGuard</a></li><li><a href="global.html#wrapInjected">wrapInjected</a></li></ul>
     
 </nav>
 
@@ -71,7 +71,7 @@
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Thu Sep 24 2026 13:05:11 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Oct 02 2026 20:53:56 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/server_WWebPerm.mjs.html

@@ -29,7 +29,7 @@
 <nav >
     
     
-    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WWebPerm.html">WWebPerm</a></li></ul><h3>Global</h3><ul><li><a href="global.html#fetchJson">fetchJson</a></li><li><a href="global.html#mergePickKeysOnly">mergePickKeysOnly</a></li></ul>
+    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WWebPerm.html">WWebPerm</a></li></ul><h3>Global</h3><ul><li><a href="global.html#createLegendMeasurer">createLegendMeasurer</a></li><li><a href="global.html#createLockSave">createLockSave</a></li><li><a href="global.html#decideLegendType">decideLegendType</a></li><li><a href="global.html#describeUpstream">describeUpstream</a></li><li><a href="global.html#fetchJson">fetchJson</a></li><li><a href="global.html#genLegend">genLegend</a></li><li><a href="global.html#maskQuery">maskQuery</a></li><li><a href="global.html#maskTok">maskTok</a></li><li><a href="global.html#maskUrl">maskUrl</a></li><li><a href="global.html#mergePickKeysOnly">mergePickKeysOnly</a></li><li><a href="global.html#reuseDeletedIds">reuseDeletedIds</a></li><li><a href="global.html#submitGuard">submitGuard</a></li><li><a href="global.html#wrapInjected">wrapInjected</a></li></ul>
     
 </nav>
 
@@ -70,14 +70,18 @@ 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 ds from '../src/schema/index.mjs'
 import { getUserRules } from '../src/plugins/mShare.mjs'
 import procCore from './procCore.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'
 
 
 /**
@@ -87,9 +91,9 @@ import procStaInfor from './procStaInfor.mjs'
  * @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 宣稱之值複寫
- * @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' 後再經本函數)
- * @param {Function} verifyAppUser 輸入驗證應用程序使用者身份之處理函數，函數會傳入使用者資訊物件，通過此函數識別後回傳布林值，允許使用者回傳true，反之回傳false
+ * @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} verifyAppUser 輸入驗證應用程序使用者身份之處理函數，函數會傳入使用者資訊物件，通過此函數識別後回傳布林值，允許使用者回傳true，反之回傳false；函數拋錯或reject時視同回傳false
  * @param {Object} [opt={}] 輸入設定物件，預設{}
  * @param {Integer} [opt.serverPort=11006] 輸入伺服器通訊port，預設11006
  * @param {Boolean} [opt.useCheckUser=false] 輸入是否檢查使用者資訊布林值，預設false
@@ -157,7 +161,7 @@ import procStaInfor from './procStaInfor.mjs'
  *             isAdmin: 'y',
  *         }
  *     }
- *     console.log('invalid token', token)
+ *     console.log('invalid token') //勿印權杖值
  *     console.log('於生產環境時得加入SSO等驗證token機制')
  *     return {}
  * }
@@ -321,6 +325,27 @@ function WWebPerm(WOrm, url, db, getUserByToken, verifyClientUser, verifyAppUser
     let srLog = srLogInit(opt)
 
 
+    //注入函數一律經包裝(W 契約, spec/設計要點與取捨.md ADR-023), 以包裝版取代三個參數
+    //why: 注入函數拋錯或 reject 時原會被 await 原樣上拋, 其原文經 pm2resolve 回前端、經 verifyConn 之 msg 入 srLog、經 error 事件印出;
+    //部署方常以 w-web-sso 對外 helper(≤1.1.4)包裝 getUserByToken, 其 reject 字串含已代入系統介接權杖與使用者權杖之完整網址.
+    //包裝後失敗視同否定結果(getUserByToken → null 等同查無, verify* → false 等同無權限), 走各呼叫點既有分支回自家 key;
+    //上游原文不回前端、不入 log, 只於此記 warn(白名單 key, 或型別與 Error.name). 同一次失敗 log 2~3 筆: 此處 warn(因) + 呼叫點 error(果).
+    //以下取代後, 本函數內除此三行外不得再直接使用原始參數(盤點見 CLAUDE_rulebook.md「權杖不外洩」, 測試 unit-wrapInjected WRAP-SITE-*)
+    let logInjectFail = (name) => {
+        return (d) => {
+            srLog.warn({ event: `inject-${name}-fail`, ...d })
+        }
+    }
+    getUserByToken = wrapInjected(getUserByToken, { failValue: null, onFail: logInjectFail('getUserByToken') })
+    verifyClientUser = wrapInjected(verifyClientUser, { failValue: false, onFail: logInjectFail('verifyClientUser') })
+    verifyAppUser = wrapInjected(verifyAppUser, { failValue: false, onFail: logInjectFail('verifyAppUser') })
+    //getUserById: 第四個注入函數(選填; useCheckUser=true 時由 WServOrm 於 execute 內呼叫, 原 reject 原文經 pm2resolve 回前端), 有給才包裝;
+    //失敗 → null 等同查無, 由 WServOrm 既有之查無分支拒絕(fail-closed). 須於 WServOrm 建構前取代(建構時即取走此函數)
+    if (isfun(getUserById)) {
+        getUserById = wrapInjected(getUserById, { failValue: null, onFail: logInjectFail('getUserById') })
+    }
+
+
     //WServOrm
     let optWServOrm = {
         useCheckUser,
@@ -344,8 +369,14 @@ function WWebPerm(WOrm, url, db, getUserByToken, verifyClientUser, verifyAppUser
     let kmx = pmKeyMutex()
 
 
+    //lockSave: 後台整表寫入(updateTabItems)之雙擊防護(後端, 見 lockSave.mjs, ADR-025): 以「updateTabItems:{表名}:{操作者 id}」於 cacheSt 原子占位,
+    //同一操作者之同表寫入處理中再送出即 reject 'saveInProgress'(不排隊); 包在 kmx 之外層, 不同操作者之並行仍由 kmx 序列化(ADR-012)
+    let cst = cacheSt()
+    let lockSave = createLockSave(cst)
+
+
     //procCore: 整表批次 diff 寫入邏輯 (updateTabItems + updateTargets/Pemis/Grups/Users)
-    let pc = procCore(woItems, procOrm, { srLog, kmx })
+    let pc = procCore(woItems, procOrm, { srLog, kmx, lockSave })
 
 
     //procStaInfor: 統計資訊, fdLog 對齊 srLog 使用同一目錄(讀 settings.logFd, fallback 邏輯同 srLog.mjs); mock 由 settings.staEventMock 注入(e2e 統計圖穩定用)
@@ -443,7 +474,7 @@ function WWebPerm(WOrm, url, db, getUserByToken, verifyClientUser, verifyAppUser
 
         //check
         if (!iseobj(userSelf)) {
-            console.log(`token`, token)
+            console.log(`token`, maskTok(token))
             srLog.error({ event: 'getTokenUser-error', msg: 'cannotFindUserFromToken' })
             return Promise.reject(`cannotFindUserFromToken`)
         }
@@ -525,7 +556,7 @@ function WWebPerm(WOrm, url, db, getUserByToken, verifyClientUser, verifyAppUser
 
         //check
         if (!iseobj(user)) {
-            console.log(`token`, token)
+            console.log(`token`, maskTok(token))
             srLog.error({ event: 'getAndVerifyAppUser-error', msg: 'cannotFindUserFromToken' })
             return Promise.reject(`cannotFindUserFromToken`)
         }
@@ -797,8 +828,8 @@ function WWebPerm(WOrm, url, db, getUserByToken, verifyClientUser, verifyAppUser
 
                     //check
                     if (!isestr(token)) {
-                        console.log('req.query', get(req, 'query'))
-                        console.log('token', token)
+                        console.log('req.query', maskQuery(get(req, 'query')))
+                        console.log('token', maskTok(token))
                         console.log('[API]getUserByToken/check token: invalid token')
                         srLog.error({ event: 'api/getUserByToken-error', msg: 'tokenNoPermission' })
                         return Promise.reject(`tokenNoPermission`)
@@ -810,7 +841,7 @@ function WWebPerm(WOrm, url, db, getUserByToken, verifyClientUser, verifyAppUser
 
                     //check
                     if (!iseobj(user)) {
-                        console.log('token', token)
+                        console.log('token', maskTok(token))
                         console.log('[API]getUserByToken/check user: invalid user')
                         srLog.error({ event: 'api/getUserByToken-error', msg: 'tokenNoPermission' })
                         return Promise.reject(`tokenNoPermission`)
@@ -847,8 +878,8 @@ function WWebPerm(WOrm, url, db, getUserByToken, verifyClientUser, verifyAppUser
 
                     //check
                     if (!isestr(token)) {
-                        console.log('req.query', get(req, 'query'))
-                        console.log('token', token)
+                        console.log('req.query', maskQuery(get(req, 'query')))
+                        console.log('token', maskTok(token))
                         console.log('[API]getPerm/check token: invalid token')
                         srLog.error({ event: 'api/getPerm-error', msg: 'tokenNoPermission' })
                         return Promise.reject(`tokenNoPermission`)
@@ -860,7 +891,7 @@ function WWebPerm(WOrm, url, db, getUserByToken, verifyClientUser, verifyAppUser
 
                     //check
                     if (!iseobj(userSelf)) {
-                        console.log('token', token)
+                        console.log('token', maskTok(token))
                         console.log('[API]getPerm/check userSelf: invalid userSelf')
                         srLog.error({ event: 'api/getPerm-error', msg: 'tokenNoPermission' })
                         return Promise.reject(`tokenNoPermission`)
@@ -872,7 +903,7 @@ function WWebPerm(WOrm, url, db, getUserByToken, verifyClientUser, verifyAppUser
 
                     //check
                     if (!isestr(userIdSelf)) {
-                        console.log('token', token)
+                        console.log('token', maskTok(token))
                         console.log('userSelf', userSelf)
                         console.log('[API]getPerm/check userIdSelf: invalid userIdSelf')
                         srLog.error({ event: 'api/getPerm-error', msg: 'tokenNoPermission' })
@@ -885,7 +916,7 @@ function WWebPerm(WOrm, url, db, getUserByToken, verifyClientUser, verifyAppUser
 
                     //check
                     if (!iseobj(userWithRulesSelf)) {
-                        console.log('token', token)
+                        console.log('token', maskTok(token))
                         console.log('userSelf', userSelf)
                         console.log('userIdSelf', userIdSelf)
                         console.log('[API]getPerm/check userWithRulesSelf: invalid userWithRulesSelf')
@@ -924,7 +955,7 @@ function WWebPerm(WOrm, url, db, getUserByToken, verifyClientUser, verifyAppUser
 
                     //check
                     if (!isestr(tokenSelf)) {
-                        console.log('req.query', get(req, 'query'))
+                        console.log('req.query', maskQuery(get(req, 'query')))
                         console.log('[API]getPermUserInfor/check tokenSelf: invalid tokenSelf')
                         srLog.error({ event: 'api/getPermUserInfor-error', msg: 'tokenNoPermission' })
                         return Promise.reject(`tokenNoPermission`)
@@ -936,8 +967,8 @@ function WWebPerm(WOrm, url, db, getUserByToken, verifyClientUser, verifyAppUser
 
                     //check
                     if (!iseobj(userSelf)) {
-                        console.log('req.query', get(req, 'query'))
-                        console.log('tokenSelf', tokenSelf)
+                        console.log('req.query', maskQuery(get(req, 'query')))
+                        console.log('tokenSelf', maskTok(tokenSelf))
                         console.log('[API]getPermUserInfor/check userSelf: invalid userSelf')
                         srLog.error({ event: 'api/getPermUserInfor-error', msg: 'tokenNoPermission' })
                         return Promise.reject(`tokenNoPermission`)
@@ -949,8 +980,8 @@ function WWebPerm(WOrm, url, db, getUserByToken, verifyClientUser, verifyAppUser
 
                     //check
                     if (!isestr(userIdFind)) {
-                        console.log('req.query', get(req, 'query'))
-                        console.log('tokenSelf', tokenSelf)
+                        console.log('req.query', maskQuery(get(req, 'query')))
+                        console.log('tokenSelf', maskTok(tokenSelf))
                         console.log('[API]getPermUserInfor/check userIdFind: invalid userIdFind')
                         srLog.error({ event: 'api/getPermUserInfor-error', msg: 'tokenNoPermission' })
                         return Promise.reject(`tokenNoPermission`)
@@ -999,8 +1030,8 @@ function WWebPerm(WOrm, url, db, getUserByToken, verifyClientUser, verifyAppUser
 
                     //check
                     if (!isestr(token)) {
-                        console.log('req.query', get(req, 'query'))
-                        console.log('token', token)
+                        console.log('req.query', maskQuery(get(req, 'query')))
+                        console.log('token', maskTok(token))
                         console.log('[API]syncAndReplaceTabs/check token: invalid token')
                         srLog.error({ event: 'api/syncAndReplaceTabs-error', msg: 'tokenNoPermission' })
                         return Promise.reject(`tokenNoPermission`)
@@ -1011,7 +1042,7 @@ function WWebPerm(WOrm, url, db, getUserByToken, verifyClientUser, verifyAppUser
 
                     //check
                     if (!isestr(keyTable)) {
-                        console.log('req.query', get(req, 'query'))
+                        console.log('req.query', maskQuery(get(req, 'query')))
                         console.log('keyTable', keyTable)
                         console.log('[API]syncAndReplaceTabs/check keyTable: invalid keyTable')
                         srLog.error({ event: 'api/syncAndReplaceTabs-error', msg: 'tokenNoPermission' })
@@ -1031,7 +1062,7 @@ function WWebPerm(WOrm, url, db, getUserByToken, verifyClientUser, verifyAppUser
 
                     //check user
                     if (!iseobj(user)) {
-                        console.log('token', token)
+                        console.log('token', maskTok(token))
                         console.log('[API]syncAndReplaceTabs/check user: invalid user')
                         srLog.error({ event: 'api/syncAndReplaceTabs-error', msg: 'tokenNoPermission' })
                         return Promise.reject(`tokenNoPermission`)
@@ -1042,7 +1073,7 @@ function WWebPerm(WOrm, url, db, getUserByToken, verifyClientUser, verifyAppUser
 
                     //check userId
                     if (!isestr(userId)) {
-                        console.log('token', token)
+                        console.log('token', maskTok(token))
                         console.log('user', user)
                         console.log('[API]syncAndReplaceTabs/check userId: invalid userId')
                         srLog.error({ event: 'api/syncAndReplaceTabs-error', msg: 'tokenNoPermission' })
@@ -1099,8 +1130,9 @@ function WWebPerm(WOrm, url, db, getUserByToken, verifyClientUser, verifyAppUser
             //check
             if (!isestr(token)) {
                 console.log('apiType', apiType)
-                console.log('authorization', authorization)
+                console.log('authorization', maskTok(authorization))
                 console.log('invalid token')
+                srLog.error({ event: 'verifyConn-error', ok: false, apiType, msg: 'tokenNoPermission' }) //認證失敗須入 log 供稽核/統計(CLAUDE.md「log 記錄要點」; 同 w-web-api、w-web-task); 只記 key, 不記 authorization 原值
                 return false
             }
 
@@ -1125,8 +1157,8 @@ function WWebPerm(WOrm, url, db, getUserByToken, verifyClientUser, verifyAppUser
             //origin
             let origin = get(headers, 'origin', '')
 
-            //referer
-            let referer = get(headers, 'referer', '')
+            //referer, 只記 origin + pathname(ADR-023): 前端以 ?token= 開站(w-ui-loginout 讀完不清網址), 同源請求之 Referer 預設帶完整網址, 原樣記錄即把使用者權杖寫入 srLog
+            let referer = maskUrl(get(headers, 'referer', ''))
 
             //info, 失敗時 msg 為 err key(cannotFindUserFromToken / cannotGetUserFromPerm / userNoPermission 等), 供資安稽核與統計
             if (b) {
@@ -1143,7 +1175,7 @@ function WWebPerm(WOrm, url, db, getUserByToken, verifyClientUser, verifyAppUser
             let user = await getUserByToken(token)
             let userId = get(user, 'id', '')
             if (!isestr(userId)) {
-                console.log('token', token)
+                console.log('token', maskTok(token))
                 console.log('userId', userId)
                 srLog.error({ event: 'getUserIdByToken-error', msg: 'cannotFindUserId' })
                 return Promise.reject(`cannotFindUserId`)
@@ -1221,7 +1253,7 @@ export default WWebPerm
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Thu Sep 24 2026 13:05:11 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Oct 02 2026 20:53:56 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/server_lockSave.mjs.html

@@ -0,0 +1,115 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    
+    <meta charset="utf-8">
+    <title>server/lockSave.mjs - Documentation</title>
+    
+    
+    <script src="scripts/prettify/prettify.js"></script>
+    <script src="scripts/prettify/lang-css.js"></script>
+    <!--[if lt IE 9]>
+      <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
+    <![endif]-->
+    <link type="text/css" rel="stylesheet" href="styles/prettify.css">
+    <link type="text/css" rel="stylesheet" href="styles/jsdoc.css">
+    <script src="scripts/nav.js" defer></script>
+    
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+</head>
+<body>
+
+<input type="checkbox" id="nav-trigger" class="nav-trigger" />
+<label for="nav-trigger" class="navicon-button x">
+  <div class="navicon"></div>
+</label>
+
+<label for="nav-trigger" class="overlay"></label>
+
+<nav >
+    
+    
+    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WWebPerm.html">WWebPerm</a></li></ul><h3>Global</h3><ul><li><a href="global.html#createLegendMeasurer">createLegendMeasurer</a></li><li><a href="global.html#createLockSave">createLockSave</a></li><li><a href="global.html#decideLegendType">decideLegendType</a></li><li><a href="global.html#describeUpstream">describeUpstream</a></li><li><a href="global.html#fetchJson">fetchJson</a></li><li><a href="global.html#genLegend">genLegend</a></li><li><a href="global.html#maskQuery">maskQuery</a></li><li><a href="global.html#maskTok">maskTok</a></li><li><a href="global.html#maskUrl">maskUrl</a></li><li><a href="global.html#mergePickKeysOnly">mergePickKeysOnly</a></li><li><a href="global.html#reuseDeletedIds">reuseDeletedIds</a></li><li><a href="global.html#submitGuard">submitGuard</a></li><li><a href="global.html#wrapInjected">wrapInjected</a></li></ul>
+    
+</nav>
+
+<div id="main">
+    
+    <h1 class="page-title">server/lockSave.mjs</h1>
+    
+
+    
+
+
+
+    
+    <section>
+        <article>
+            <pre class="prettyprint source linenums"><code>import get from 'lodash-es/get.js'
+import isestr from 'wsemi/src/isestr.mjs'
+
+
+/**
+ * 有副作用之寫入路徑(如清單儲存 updateUsersList / updateTokensList / updateIpsList)之雙擊防護(後端, ADR-025)
+ *
+ * 以「操作:操作者 id」於 wsemi cacheSt 原子占位執行 fn, 同一操作者之同一操作處理中再送出即 reject 錯誤 key
+ * (預設 'saveInProgress', 可以 opt.errKey 指定; 皆為 i18n key, 見 procLang); 不同操作者、不同操作互不影響;
+ * fn 之 reject 原樣 bubble; fn 結束(含失敗)即釋放.
+ * 第 2 次不排隊執行: 其內容與第 1 次相同, 排隊後再寫一次會把第 1 次剛建立之列當修改覆寫
+ * (依序重送另由各專案之資料層檢查擋, 如 SSO procCore.updateTabItems 之新增列檢查回 'saveNewRowExists').
+ * operatorId 可為操作者 id 或「操作者 id + 列識別」(只擋同一列之連發, 同批其他列不受影響).
+ *
+ * @param {Object} cst 輸入 wsemi cacheSt 實例
+ * @returns {Function} 回傳 async (op, operatorId, fn, opt = {}) => fn 之結果, opt.errKey 為占位衝突時 reject 之 key
+ */
+function createLockSave(cst) {
+
+    let lockSave = async (op, operatorId, fn, opt = {}) => {
+
+        //errKey
+        let errKey = get(opt, 'errKey', '')
+        if (!isestr(errKey)) {
+            errKey = 'saveInProgress'
+        }
+
+        let key = `${op}:${operatorId}`
+        return await cst.setWithFree([key], fn)
+            .catch((err) => {
+                //remap setWithFree 之占位衝突 → i18n key; fn 內之 reject 原樣 bubble
+                if (err === `setWithFree: key in use: ${key}`) {
+                    return Promise.reject(errKey)
+                }
+                return Promise.reject(err)
+            })
+    }
+
+    return lockSave
+}
+
+
+export default createLockSave
+</code></pre>
+        </article>
+    </section>
+
+
+
+
+    
+    
+</div>
+
+<br class="clear">
+
+<footer>
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Oct 02 2026 20:53:56 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+</footer>
+
+<script>prettyPrint();</script>
+<script src="scripts/polyfill.js"></script>
+<script src="scripts/linenumber.js"></script>
+
+
+
+</body>
+</html>

package/docs/server_maskLog.mjs.html

@@ -0,0 +1,176 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    
+    <meta charset="utf-8">
+    <title>server/maskLog.mjs - Documentation</title>
+    
+    
+    <script src="scripts/prettify/prettify.js"></script>
+    <script src="scripts/prettify/lang-css.js"></script>
+    <!--[if lt IE 9]>
+      <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
+    <![endif]-->
+    <link type="text/css" rel="stylesheet" href="styles/prettify.css">
+    <link type="text/css" rel="stylesheet" href="styles/jsdoc.css">
+    <script src="scripts/nav.js" defer></script>
+    
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+</head>
+<body>
+
+<input type="checkbox" id="nav-trigger" class="nav-trigger" />
+<label for="nav-trigger" class="navicon-button x">
+  <div class="navicon"></div>
+</label>
+
+<label for="nav-trigger" class="overlay"></label>
+
+<nav >
+    
+    
+    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WWebPerm.html">WWebPerm</a></li></ul><h3>Global</h3><ul><li><a href="global.html#createLegendMeasurer">createLegendMeasurer</a></li><li><a href="global.html#createLockSave">createLockSave</a></li><li><a href="global.html#decideLegendType">decideLegendType</a></li><li><a href="global.html#describeUpstream">describeUpstream</a></li><li><a href="global.html#fetchJson">fetchJson</a></li><li><a href="global.html#genLegend">genLegend</a></li><li><a href="global.html#maskQuery">maskQuery</a></li><li><a href="global.html#maskTok">maskTok</a></li><li><a href="global.html#maskUrl">maskUrl</a></li><li><a href="global.html#mergePickKeysOnly">mergePickKeysOnly</a></li><li><a href="global.html#reuseDeletedIds">reuseDeletedIds</a></li><li><a href="global.html#submitGuard">submitGuard</a></li><li><a href="global.html#wrapInjected">wrapInjected</a></li></ul>
+    
+</nav>
+
+<div id="main">
+    
+    <h1 class="page-title">server/maskLog.mjs</h1>
+    
+
+    
+
+
+
+    
+    <section>
+        <article>
+            <pre class="prettyprint source linenums"><code>import isestr from 'wsemi/src/isestr.mjs'
+import isarr from 'wsemi/src/isarr.mjs'
+
+
+//maskLog: 權杖與網址寫入 console / srLog 前之遮罩(M 契約, spec/設計要點與取捨.md ADR-023)
+//四 repo 一致(w-web-sso server/srLog.mjs 之 maskToken 與 src/maskUrl.mjs、w-web-api / w-web-task 之 maskTok), 以同一組測資守護(test/unit-maskLog.test.mjs)
+//why: 原 console 站點原樣印出 token / req.query / authorization(Hapi 對重複之 query 參數給陣列, 型別檢查失敗之分支正是印出處), verifyConn 之 srLog 原樣記 referer
+
+
+//safe: 露出字元之控制字元換成 '?', 避免請求端以 CR/LF 偽造 log 行
+function safe(s) {
+    return Array.from(s, (c) => {
+        let x = c.charCodeAt(0)
+        return (x &lt; 32 || x === 127) ? '?' : c
+    }).join('')
+}
+
+
+/**
+ * 權杖遮罩
+ * - 空值(undefined / null / '')回 ''
+ * - 陣列逐元素遮罩
+ * - 字串(長度 n)露出前後各 k=min(4, floor(n/8)) 字: k=0 只回 '(len=n)', 否則 '前k...後k(len=n)'; 36 字元之 session token 為前 4 後 4(與 w-web-sso 格式相同)
+ * - 其他型別只回 '(typeof)', 絕不輸出原值
+ *
+ * @param {*} token 輸入權杖
+ * @returns {String|Array} 回傳遮罩後字串, 輸入陣列時回傳陣列
+ */
+function maskTok(token) {
+    if (isarr(token)) {
+        return token.map(maskTok)
+    }
+    if (token === undefined || token === null || token === '') {
+        return ''
+    }
+    if (!isestr(token)) {
+        return `(${typeof token})`
+    }
+    let n = token.length
+    let k = Math.min(4, Math.floor(n / 8))
+    if (k === 0) {
+        return `(len=${n})`
+    }
+    return `${safe(token.slice(0, k))}...${safe(token.slice(-k))}(len=${n})`
+}
+
+
+/**
+ * 查詢參數遮罩: 淺拷貝, 鍵名小寫為 token 者以 maskTok 處理, 其餘原樣(供印出 req.query)
+ * 非物件輸入依 maskTok 處理
+ *
+ * @param {*} q 輸入查詢參數物件(Hapi 之 req.query 為 null-prototype 物件)
+ * @returns {Object|String|Array} 回傳遮罩後之淺拷貝
+ */
+function maskQuery(q) {
+    if (q === null || typeof q !== 'object' || isarr(q)) {
+        return maskTok(q)
+    }
+    let r = {}
+    for (let k of Object.keys(q)) {
+        r[k] = (k.toLowerCase() === 'token') ? maskTok(q[k]) : q[k]
+    }
+    return r
+}
+
+
+/**
+ * 網址遮罩: http(s) 只留 origin + pathname, 捨棄 query / fragment / userinfo(其內常含權杖, 如 ?token=)
+ * - 陣列逐元素處理; 空值回 ''; 其他非字串只回 '(typeof)'
+ * - 非 http(s) 之網址(如 data:、javascript:)路徑即全部內容, 只回 protocol(同 w-web-sso src/maskUrl.mjs)
+ * - 無法解析回 '(invalid-url)'
+ *
+ * @param {*} u 輸入網址
+ * @returns {String|Array} 回傳可寫入 log 之字串, 輸入陣列時回傳陣列
+ */
+function maskUrl(u) {
+    if (isarr(u)) {
+        return u.map(maskUrl)
+    }
+    if (u === undefined || u === null || u === '') {
+        return ''
+    }
+    if (!isestr(u)) {
+        return `(${typeof u})`
+    }
+    let x = null
+    try {
+        x = new URL(u)
+    }
+    catch (err) {
+        return '(invalid-url)'
+    }
+    if (x.protocol !== 'http:' &amp;&amp; x.protocol !== 'https:') {
+        return x.protocol
+    }
+    return `${x.origin}${x.pathname}`
+}
+
+
+export {
+    maskTok,
+    maskQuery,
+    maskUrl
+}
+</code></pre>
+        </article>
+    </section>
+
+
+
+
+    
+    
+</div>
+
+<br class="clear">
+
+<footer>
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Oct 02 2026 20:53:56 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+</footer>
+
+<script>prettyPrint();</script>
+<script src="scripts/polyfill.js"></script>
+<script src="scripts/linenumber.js"></script>
+
+
+
+</body>
+</html>