w-web-sso 1.1.11 → 1.1.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. package/README.md +28 -2
  2. package/dist/css/{app.b17b0ba0.css → app.f000459f.css} +1 -1
  3. package/dist/index.tmp +1 -1
  4. package/dist/js/{app-legacy.bee6840f.js → app-legacy.7c006893.js} +1 -1
  5. package/dist/js/{app.bee6840f.js → app.7c006893.js} +1 -1
  6. package/dist/js/{chunk-vendors.0492b6f5.js → chunk-vendors-legacy.97013ddc.js} +5 -5
  7. package/dist/js/{chunk-vendors-legacy.0492b6f5.js → chunk-vendors.97013ddc.js} +5 -5
  8. package/dist/w-web-sso.umd.js +4 -4
  9. package/dist/w-web-sso.umd.js.map +1 -1
  10. package/docs/WWebSso.html +5 -4
  11. package/docs/global.html +3 -3
  12. package/docs/index.html +1 -1
  13. package/docs/server_WWebSso.mjs.html +24 -16
  14. package/docs/server_getIgnoredOrmKeys.mjs.html +1 -1
  15. package/docs/server_lockSave.mjs.html +1 -1
  16. package/docs/server_ormWrite.mjs.html +1 -1
  17. package/docs/server_staLogs_resolveShellWorker.mjs.html +1 -1
  18. package/docs/server_wrapTimer.mjs.html +1 -1
  19. package/docs/src_components_Common_CheckYesNo.vue.html +1 -1
  20. package/docs/src_fetchSsoMsg.mjs.html +15 -2
  21. package/docs/src_httpGetJson.mjs.html +1 -1
  22. package/docs/src_maskUrl.mjs.html +1 -1
  23. package/docs/src_plugins_staUsage.mjs.html +1 -1
  24. package/docs/src_plugins_submitGuard.mjs.html +1 -1
  25. package/package.json +2 -2
  26. package/server/WWebSso.mjs +23 -15
  27. package/server/procCore.mjs +800 -382
  28. package/server/procLang.mjs +23 -0
  29. package/server/procProtect.mjs +300 -117
  30. package/server/srLog.mjs +31 -8
  31. package/src/baselineOf.mjs +76 -0
  32. package/src/components/LayoutContentIps.vue +24 -2
  33. package/src/components/LayoutContentTokens.vue +24 -2
  34. package/src/components/LayoutContentUsers.vue +9 -3
  35. package/src/fetchSsoMsg.mjs +14 -1
  36. package/src/getUserByToken.mjs +2 -2
  37. package/src/getUserByUserId.mjs +2 -2
  38. package/src/getUsersByToken.mjs +2 -2
  39. package/src/schema/tables/ips.mjs +4 -0
  40. package/src/schema/tables/tokens.mjs +4 -0
  41. package/src/writeContracts/index.mjs +9 -0
  42. package/src/writeContracts/ips.mjs +9 -0
  43. package/src/writeContracts/tokens.mjs +12 -0
  44. package/src/writeContracts/tokensSession.mjs +10 -0
  45. package/src/writeContracts/users.mjs +15 -0
@@ -846,6 +846,11 @@ let kpLang = {
846
846
  eng: 'Token does not have permission.',
847
847
  cht: '權杖無存取權限。',
848
848
  },
849
+ //外部 API 查詢 (getSsoUserInfor / kpfun getUserInfor): 查詢欄位名不在白名單 id / account / email / name (R-QKEY-01; 外部錯誤回 key, 不回顯欄位名與查詢值)
850
+ invalidUserQueryKey: {
851
+ eng: 'Invalid query field. Please use id, account, email or name.',
852
+ cht: '查詢欄位無效,請使用 id、account、email 或 name。',
853
+ },
849
854
  // tokenInvalid: {
850
855
  // eng: 'Your session has expired. Please log in again.',
851
856
  // cht: '登入逾時,請重新登入。',
@@ -1008,6 +1013,10 @@ let kpLang = {
1008
1013
  eng: 'Invalid app token permissions.',
1009
1014
  cht: '應用系統金鑰權限設定無效。',
1010
1015
  },
1016
+ tokenSessionAddNotAllowed: { //金鑰清單存檔不得新增登入權杖(session 列; ADR-092)
1017
+ eng: 'Login tokens cannot be added. Nothing was saved.',
1018
+ cht: '不可新增登入權杖,本次未儲存任何變更',
1019
+ },
1011
1020
  //應用系統金鑰之各權限名稱, 鍵為 appPerm_<權限字串> (權限全集見 src/appPerms.mjs)
1012
1021
  appPerm_readUsers: {
1013
1022
  eng: 'Read users',
@@ -1319,6 +1328,20 @@ let kpLang = {
1319
1328
  cht: `資料寫入未全部完成,部分變更可能已生效,請重新整理頁面確認後再操作`,
1320
1329
  },
1321
1330
 
1331
+ //多人同時編輯之寫入契約(原則 10): 拒收鍵 baselineMismatch / rowNotFound / baselineFormat 由 procCore.getSaveRejectKey 轉為下列語系鍵, 一律提示重新載入; 拒收時零寫入
1332
+ saveStale: { //載入後資料已被他人或系統更動(baselineMismatch)
1333
+ eng: `The data has been changed by another user or the system since you loaded this page. Nothing was saved. Please reload the page and make your changes again.`,
1334
+ cht: `資料自您載入後已被其他使用者或系統更動,本次未儲存任何變更,請重新載入頁面後再操作`,
1335
+ },
1336
+ saveRowNotFound: { //要修改或刪除之資料已不存在(rowNotFound)
1337
+ eng: `Some of the data no longer exists (it may have been deleted by another user). Nothing was saved. Please reload the page and make your changes again.`,
1338
+ cht: `部分資料已不存在(可能已被其他使用者刪除),本次未儲存任何變更,請重新載入頁面後再操作`,
1339
+ },
1340
+ saveBaselineFormat: { //前端送出之載入基準格式或版本不識(baselineFormat)
1341
+ eng: `The page data version is not recognized. Nothing was saved. Please reload the page and make your changes again.`,
1342
+ cht: `頁面資料版本無法辨識,本次未儲存任何變更,請重新載入頁面後再操作`,
1343
+ },
1344
+
1322
1345
  }
1323
1346
 
1324
1347
 
@@ -1,5 +1,6 @@
1
1
  import path from 'path'
2
2
  import fs from 'fs'
3
+ import { isIP } from 'net'
3
4
  import ot from 'dayjs'
4
5
  import get from 'lodash-es/get.js'
5
6
  import each from 'lodash-es/each.js'
@@ -28,15 +29,30 @@ import pm2resolve from 'wsemi/src/pm2resolve.mjs'
28
29
  import pmSeries from 'wsemi/src/pmSeries.mjs'
29
30
  import getErrorMessage from 'wsemi/src/getErrorMessage.mjs'
30
31
  import ds from '../src/schema/index.mjs'
31
- import ormWrite from './ormWrite.mjs'
32
32
  import wrapTimer from './wrapTimer.mjs'
33
- import { maskToken } from './srLog.mjs'
33
+ import { maskToken, safeText } from './srLog.mjs'
34
+
35
+
36
+ //來源 IP 取自 X-Forwarded-For 之值: 合法 IP 之長度上限(IPv6 文字最長 45 字元, 外加 zone 識別碼; net.isIP 對 zone 識別碼長度無上限,
37
+ // 單獨依 isIP 時 `::1%` 加萬字元仍被判為 IP)、非合法 IP 時之 warn 限流間隔(ms)與預覽長度 (R-IP-01)
38
+ let FORWARDED_IP_MAX_LEN = 64
39
+ let FORWARDED_WARN_INTERVAL_MS = 10 * 1000
40
+ let FORWARDED_PREVIEW_LEN = 64
41
+
42
+ //來源 IP 之帶 port 形式(去 port 取 IP 之唯一正規化, R-IP-01): IPv4:port 與括號形式 [IPv6]:port; port 為 1~5 位十進位數字且不得超過 FORWARDED_PORT_MAX
43
+ let FORWARDED_RE_V4_PORT = /^(\d{1,3}(?:\.\d{1,3}){3}):(\d{1,5})$/
44
+ let FORWARDED_RE_V6_PORT = /^\[([^[\]]+)\]:(\d{1,5})$/
45
+ let FORWARDED_PORT_MAX = 65535
34
46
 
35
47
 
36
48
  function proc(woItems, p, opt = {}) {
37
49
 
38
50
  //params
51
+ //procOrm / withTabLocks: 取自 w-serv-orm 實例(與 procCore 同一組, 同表只由同一鎖管理器寫入, 規格 §12); 系統直寫 users / tokens / ips 一律在該表表鎖內、
52
+ //經 procOrm 且 mustExist(只改不增), 更新者記常數 'system' (R-CONC-01, R-CONC-04, 決策 D7)
39
53
  let {
54
+ procOrm,
55
+ withTabLocks,
40
56
  srLog,
41
57
  minForAccountLoginFailed,
42
58
  numForAccountLoginFailed,
@@ -49,6 +65,14 @@ function proc(woItems, p, opt = {}) {
49
65
  minBlockForIpCallApi,
50
66
  } = opt
51
67
 
68
+ //check
69
+ if (!isfun(procOrm) || !isfun(withTabLocks)) {
70
+ throw new Error('procProtect needs procOrm and withTabLocks from the WServOrm instance')
71
+ }
72
+
73
+ //SYSTEM_ID: 無使用者可歸屬之系統寫入(計時器、自動封鎖)記於 userIdUpdate 之常數
74
+ let SYSTEM_ID = 'system'
75
+
52
76
 
53
77
  //logError: 封鎖寫入失敗之紀錄 (ADR-080); srLog 未給時略過, 同 blockAccountByToken 之 debug 守衛
54
78
  let logError = (o) => {
@@ -70,6 +94,27 @@ function proc(woItems, p, opt = {}) {
70
94
  let mkKp = () => Object.create(null)
71
95
 
72
96
 
97
+ //pruneKpKey: 計數容器單一鍵之剪枝 (R-CNT-01, 單一擁有者): 取窗內紀錄; 窗內無紀錄則刪除該鍵(不留空陣列, 否則使用端可植入之互異字串使鍵數無上限成長),
98
+ // 有則換成只含窗內紀錄之陣列; 回傳窗內紀錄. kp[key] 已不是讀取時之 times 者回 null 且不更動:
99
+ // 計時器逐鍵 await 封鎖寫入之間, cleanKp* 可能已換掉整個容器(或該鍵已被重建 / 刪除), times 為舊快照——
100
+ // 不得以之覆蓋 / 刪除新紀錄, 呼叫端亦不得以之作為封鎖依據 (清理即取消尚未處理之鍵的舊判定)
101
+ let pruneKpKey = (kp, key, times, timeStart) => {
102
+ if (kp[key] !== times) {
103
+ return null
104
+ }
105
+ let recs = times.filter((timeRec) => {
106
+ return timeRec >= timeStart //ot(t).isAfter(timeStart)
107
+ })
108
+ if (size(recs) === 0) {
109
+ delete kp[key]
110
+ }
111
+ else {
112
+ kp[key] = recs
113
+ }
114
+ return recs
115
+ }
116
+
117
+
73
118
  //kpAccountLoginFailed
74
119
  let kpAccountLoginFailed = mkKp()
75
120
 
@@ -140,57 +185,75 @@ function proc(woItems, p, opt = {}) {
140
185
  //blockAccount
141
186
  let blockAccount = async (account) => {
142
187
 
143
- //getGenUserByAccount
188
+ //getGenUserByAccount, 取得使用者主鍵; 封鎖狀態於下方 [tokens, users] 鎖內重讀
144
189
  let u = await p.getGenUserByAccount(account)
145
190
 
146
191
  // //check, 不用檢測, 若resolve必定有, 若reject則由外部處理
147
192
  // if (!iseobj(u)) {
148
193
  // }
149
194
 
150
- //getBlockedByUser
151
- let b = await getBlockedByUser(u)
195
+ //[tokens, users] 鎖內: 重讀使用者(新鮮) → 判斷是否已封鎖 → 寫 timeBlocked → 撤銷 token, 同一把鎖完成 (S15):
196
+ //timeBlocked 為雙方欄位(後台可改、自動封鎖亦寫), 系統直寫須取表鎖, 持舊畫面之後台存檔才會被偵測而拒收 (V4); 讀到之使用者於寫入前不被刪除插隊 (X5)
197
+ await withTabLocks(['tokens', 'users'], async () => {
152
198
 
153
- //check
154
- if (b) {
155
- return //已封鎖, 禁止重複封鎖
156
- }
199
+ //帳號對應再驗: 失敗登入所針對之帳號於等鎖期間可能已被後台改名或停用, 該帳號已不屬於這位使用者則不封鎖(以鎖內新鮮狀態為準)
200
+ let usAcc = await woItems.users.select({ account, isActive: 'y' })
201
+ if (size(usAcc) !== 1 || get(usAcc[0], 'id', '') !== u.id) {
202
+ return
203
+ }
157
204
 
158
- //timeBlocked, 依照minBlockForAccountLoginFailed(min)更新封鎖時間
159
- let timeBlocked = ot().add(minBlockForAccountLoginFailed, 'minute').format('YYYY-MM-DDTHH:mm:ss.SSSZ')
160
- // console.log('timeBlocked', timeBlocked)
205
+ //重讀使用者, 已被刪除則無從封鎖(其 token 已於刪除時同鎖撤銷)
206
+ let us = await woItems.users.select({ id: u.id })
207
+ if (size(us) !== 1) {
208
+ return
209
+ }
161
210
 
162
- //封鎖使用者, 須更新使用者timeBlocked; 逐筆檢查 (ADR-080)
163
- let errBlock = null
164
- await ormWrite(woItems.users, 'save', {
165
- id: u.id,
166
- timeBlocked,
167
- })
168
- .catch((err) => {
169
- errBlock = err
170
- })
211
+ //getBlockedByUser
212
+ let b = await getBlockedByUser(us[0])
171
213
 
172
- //封鎖使用者, 須刪除該 user 名下所有 token (multi-session 強制全部登出)
173
- //(原本走 p.getTokenByKV('userId', u.id) 取單筆, 但 ADR-001 接受同帳號多 active token,
174
- //getTokenByKV 之 nts>=2 reject 'duplicate token' 對 multi-session user 必觸發 → token
175
- //完全沒刪 → 帳號被鎖但既有 session 仍可用. 改用 select 直接取陣列後全部刪除,
176
- //對齊 spec/流程_自動封鎖機制.md A32「強制登出」契約 — Round-3 audit B-01 fix.)
177
- //撤銷與刪除 / 停用使用者共用 p.revokeTokensByUserId (一次刪除並逐筆檢查); 封鎖寫入失敗仍撤銷 (依意圖 fail closed, ADR-080)
178
- let errRevoke = null
179
- await p.revokeTokensByUserId(u.id)
180
- .catch((err) => {
181
- errRevoke = err
182
- })
214
+ //check
215
+ if (b) {
216
+ return //已封鎖, 禁止重複封鎖
217
+ }
183
218
 
184
- //check, 失敗記錄後 reject; 封鎖未寫入時, 下次登入失敗仍超過門檻即再嘗試封鎖
185
- if (errBlock !== null || errRevoke !== null) {
186
- logError({
187
- event: 'fun-blockAccount',
188
- userId: u.id,
189
- errBlock: errBlock !== null ? getErrorMessage(errBlock) : '',
190
- errRevoke: errRevoke !== null ? getErrorMessage(errRevoke) : '',
191
- })
192
- return Promise.reject(`failed to block account`)
193
- }
219
+ //timeBlocked, 依照minBlockForAccountLoginFailed(min)更新封鎖時間
220
+ let timeBlocked = ot().add(minBlockForAccountLoginFailed, 'minute').format('YYYY-MM-DDTHH:mm:ss.SSSZ')
221
+ // console.log('timeBlocked', timeBlocked)
222
+
223
+ //封鎖使用者, 須更新使用者timeBlocked; 經 procOrm 且 mustExist(只改不增), 更新者記 'system'; 逐筆檢查 (ADR-080)
224
+ let errBlock = null
225
+ await procOrm(SYSTEM_ID, 'users', 'save', [{
226
+ id: u.id,
227
+ timeBlocked,
228
+ }], { mustExist: true })
229
+ .catch((err) => {
230
+ errBlock = err
231
+ })
232
+
233
+ //封鎖使用者, 須刪除該 user 名下所有 token (multi-session 強制全部登出)
234
+ //(原本走 p.getTokenByKV('userId', u.id) 取單筆, 但 ADR-001 接受同帳號多 active token,
235
+ //getTokenByKV 之 nts>=2 reject 'duplicate token' 對 multi-session user 必觸發 → token
236
+ //完全沒刪 → 帳號被鎖但既有 session 仍可用. 改用 select 直接取陣列後全部刪除,
237
+ //對齊 spec/流程_自動封鎖機制.md A32「強制登出」契約 — Round-3 audit B-01 fix.)
238
+ //撤銷與刪除 / 停用使用者共用 p.revokeTokensByUserIdLocked (持鎖版, 一次刪除並逐筆檢查); 封鎖寫入失敗仍撤銷 (依意圖 fail closed, ADR-080)
239
+ let errRevoke = null
240
+ await p.revokeTokensByUserIdLocked(u.id)
241
+ .catch((err) => {
242
+ errRevoke = err
243
+ })
244
+
245
+ //check, 失敗記錄後 reject; 封鎖未寫入時, 下次登入失敗仍超過門檻即再嘗試封鎖
246
+ if (errBlock !== null || errRevoke !== null) {
247
+ logError({
248
+ event: 'fun-blockAccount',
249
+ userId: u.id,
250
+ errBlock: errBlock !== null ? getErrorMessage(errBlock) : '',
251
+ errRevoke: errRevoke !== null ? getErrorMessage(errRevoke) : '',
252
+ })
253
+ return Promise.reject(`failed to block account`)
254
+ }
255
+
256
+ })
194
257
 
195
258
  }
196
259
 
@@ -229,8 +292,8 @@ function proc(woItems, p, opt = {}) {
229
292
  msg: u,
230
293
  }
231
294
 
232
- //清除帳號的登入失敗紀錄
233
- kpAccountLoginFailed[account] = []
295
+ //清除帳號的登入失敗紀錄 (刪鍵, 不留空陣列: R-CNT-01)
296
+ delete kpAccountLoginFailed[account]
234
297
 
235
298
  })
236
299
  .catch(async (err) => {
@@ -297,17 +360,9 @@ function proc(woItems, p, opt = {}) {
297
360
  //timeStart
298
361
  let timeStart = ot().add(-minForAccountLoginFailed, 'minute').format('YYYY-MM-DDTHH:mm:ss.SSSZ')
299
362
 
300
- //逐帳號剪枝, 窗內仍有紀錄則保留壓縮後陣列, 窗內全無則整個 delete key
363
+ //逐帳號剪枝, 窗內仍有紀錄則保留壓縮後陣列, 窗內全無則整個 delete key (pruneKpKey, R-CNT-01)
301
364
  await pmSeries(kpAccountLoginFailed, async (times, account) => {
302
- let recs = times.filter((timeRec) => {
303
- return timeRec >= timeStart
304
- })
305
- if (size(recs) === 0) {
306
- delete kpAccountLoginFailed[account]
307
- }
308
- else {
309
- kpAccountLoginFailed[account] = recs
310
- }
365
+ pruneKpKey(kpAccountLoginFailed, account, times, timeStart)
311
366
  })
312
367
 
313
368
  }, timerError), 2000)
@@ -346,55 +401,78 @@ function proc(woItems, p, opt = {}) {
346
401
  return Promise.reject(`invalid userId`)
347
402
  }
348
403
 
349
- //getGenUserByUserId
404
+ //getGenUserByUserId, 取得使用者主鍵; 封鎖狀態於下方 [tokens, users] 鎖內重讀
350
405
  let u = await p.getGenUserByUserId(userId)
351
406
 
352
407
  // //check, 不用檢測, 若resolve必定有, 若reject則由外部處理
353
408
  // if (!iseobj(u)) {
354
409
  // }
355
410
 
356
- //getBlockedByUser
357
- let b = await getBlockedByUser(u)
411
+ //[tokens, users] 鎖內: 重讀使用者(新鮮) → 判斷是否已封鎖 → 寫 timeBlocked → 撤銷 token, 同一把鎖完成 (S16; 理由同 blockAccount)
412
+ await withTabLocks(['tokens', 'users'], async () => {
358
413
 
359
- //check
360
- if (b) {
361
- return //已封鎖, 禁止重複封鎖
362
- }
414
+ //重讀 token 並再驗身分: 鎖外判定其為使用者 token 與擁有者後, 等鎖期間後台存檔可能已將其升為應用系統金鑰(受信任, 不套用個人速率封鎖)、換擁有者, 或已被登出 / 撤銷;
415
+ //身分已與鎖外判定不符則不封鎖(以鎖內新鮮狀態為準)
416
+ let tn = null
417
+ await p.getTokenByKV('token', token)
418
+ .then((r) => {
419
+ tn = r
420
+ })
421
+ .catch(() => {})
422
+ if (tn === null || get(tn, 'isApp', '') === 'y' || get(tn, 'userId', '') !== u.id) {
423
+ return
424
+ }
363
425
 
364
- //timeBlocked, 依照minBlockForTokenCallApi(min)更新封鎖時間
365
- let timeBlocked = ot().add(minBlockForTokenCallApi, 'minute').format('YYYY-MM-DDTHH:mm:ss.SSSZ')
366
- // console.log('timeBlocked', timeBlocked)
426
+ //重讀使用者, 已被刪除則無從封鎖(其 token 已於刪除時同鎖撤銷)
427
+ let us = await woItems.users.select({ id: u.id })
428
+ if (size(us) !== 1) {
429
+ return
430
+ }
367
431
 
368
- //封鎖使用者, 須更新使用者timeBlocked; 逐筆檢查 (ADR-080)
369
- let errBlock = null
370
- await ormWrite(woItems.users, 'save', {
371
- id: u.id,
372
- timeBlocked,
373
- })
374
- .catch((err) => {
375
- errBlock = err
376
- })
432
+ //getBlockedByUser
433
+ let b = await getBlockedByUser(us[0])
377
434
 
378
- //封鎖使用者, 須刪除該 user 名下所有 token (含所用 token; 與 blockAccount 同為 multi-session 強制全部登出, 共用 p.revokeTokensByUserId);
379
- //原只刪所用 token, 封鎖期間該使用者其他裝置之既有登入照常可用, 與 spec E2E-005 及登入失敗封鎖不一致 (2026-10-11 改, ADR-080)
380
- //封鎖寫入失敗仍撤銷 (依意圖 fail closed, ADR-080)
381
- let errRevoke = null
382
- await p.revokeTokensByUserId(u.id)
383
- .catch((err) => {
384
- errRevoke = err
385
- })
435
+ //check
436
+ if (b) {
437
+ return //已封鎖, 禁止重複封鎖
438
+ }
386
439
 
387
- //check, 失敗記錄後 reject
388
- if (errBlock !== null || errRevoke !== null) {
389
- logError({
390
- event: 'fun-blockAccountByToken',
391
- userId: u.id,
392
- token: maskToken(token),
393
- errBlock: errBlock !== null ? getErrorMessage(errBlock) : '',
394
- errRevoke: errRevoke !== null ? getErrorMessage(errRevoke) : '',
395
- })
396
- return Promise.reject(`failed to block account by token`)
397
- }
440
+ //timeBlocked, 依照minBlockForTokenCallApi(min)更新封鎖時間
441
+ let timeBlocked = ot().add(minBlockForTokenCallApi, 'minute').format('YYYY-MM-DDTHH:mm:ss.SSSZ')
442
+ // console.log('timeBlocked', timeBlocked)
443
+
444
+ //封鎖使用者, 須更新使用者timeBlocked; 經 procOrm 且 mustExist(只改不增), 更新者記 'system'; 逐筆檢查 (ADR-080)
445
+ let errBlock = null
446
+ await procOrm(SYSTEM_ID, 'users', 'save', [{
447
+ id: u.id,
448
+ timeBlocked,
449
+ }], { mustExist: true })
450
+ .catch((err) => {
451
+ errBlock = err
452
+ })
453
+
454
+ //封鎖使用者, 須刪除該 user 名下所有 token (含所用 token; 與 blockAccount 同為 multi-session 強制全部登出, 共用 p.revokeTokensByUserIdLocked 持鎖版);
455
+ //原只刪所用 token, 封鎖期間該使用者其他裝置之既有登入照常可用, 與 spec E2E-005 及登入失敗封鎖不一致 (2026-10-11 改, ADR-080)
456
+ //封鎖寫入失敗仍撤銷 (依意圖 fail closed, ADR-080)
457
+ let errRevoke = null
458
+ await p.revokeTokensByUserIdLocked(u.id)
459
+ .catch((err) => {
460
+ errRevoke = err
461
+ })
462
+
463
+ //check, 失敗記錄後 reject
464
+ if (errBlock !== null || errRevoke !== null) {
465
+ logError({
466
+ event: 'fun-blockAccountByToken',
467
+ userId: u.id,
468
+ token: maskToken(token),
469
+ errBlock: errBlock !== null ? getErrorMessage(errBlock) : '',
470
+ errRevoke: errRevoke !== null ? getErrorMessage(errRevoke) : '',
471
+ })
472
+ return Promise.reject(`failed to block account by token`)
473
+ }
474
+
475
+ })
398
476
 
399
477
  }
400
478
 
@@ -442,14 +520,14 @@ function proc(woItems, p, opt = {}) {
442
520
  //偵測token調用API次數
443
521
  await pmSeries(kpTokenCallApi, async (times, token) => {
444
522
 
445
- //recs, 提取指定時間範圍內的紀錄
446
- let recs = times.filter((timeRec) => {
447
- return timeRec >= timeStart //ot(t).isAfter(timeStart)
448
- })
523
+ //recs, 提取指定時間範圍內的紀錄, 並更新容器: 僅保留指定時間範圍內的紀錄, 窗內無紀錄則刪除該鍵 (pruneKpKey, R-CNT-01)
524
+ let recs = pruneKpKey(kpTokenCallApi, token, times, timeStart)
449
525
  // console.log(token, 'recs', recs)
450
526
 
451
- //更新, 僅保留指定時間範圍內的紀錄
452
- kpTokenCallApi[token] = recs
527
+ //容器或該鍵已被換掉 (times 為舊快照): 略過本鍵, 不據舊紀錄封鎖
528
+ if (recs === null) {
529
+ return
530
+ }
453
531
 
454
532
  //nrecs
455
533
  let nrecs = size(recs)
@@ -482,6 +560,74 @@ function proc(woItems, p, opt = {}) {
482
560
  }
483
561
 
484
562
 
563
+ //warnInvalidForwardedFor: X-Forwarded-For 之值非合法 IP 而退回連線位址時記 warn (R-IP-01):
564
+ // 至多每 FORWARDED_WARN_INTERVAL_MS 一筆, 期間略過之次數於下一筆以 suppressed 帶出;
565
+ // 該值為使用端可植入之任意字串, 只記長度與前 FORWARDED_PREVIEW_LEN 字元, 不整段寫入 log; srLog 未給或無 warn 函式時略過
566
+ let tsWarnForwarded = null
567
+ let nSuppressedForwarded = 0
568
+ let warnInvalidForwardedFor = (raw, ipUsed) => {
569
+ if (!(srLog && isfun(srLog.warn))) {
570
+ return
571
+ }
572
+ let now = Date.now()
573
+ if (tsWarnForwarded !== null) {
574
+ if (now < tsWarnForwarded) {
575
+ //時鐘回撥: 以現時重設窗口起點並略過本筆 (連續回撥亦不致每筆皆記)
576
+ tsWarnForwarded = now
577
+ nSuppressedForwarded++
578
+ return
579
+ }
580
+ if (now - tsWarnForwarded < FORWARDED_WARN_INTERVAL_MS) {
581
+ nSuppressedForwarded++
582
+ return
583
+ }
584
+ }
585
+ let suppressed = nSuppressedForwarded
586
+ tsWarnForwarded = now
587
+ nSuppressedForwarded = 0
588
+
589
+ //記錄失敗 (同步拋錯或回傳被 reject 之 Promise) 不得使取 IP 失敗: 使用端以非 IP 標頭即可觸發此路徑, 記錄器故障不應放大為請求失敗
590
+ try {
591
+ let r = srLog.warn({
592
+ event: 'fun-getIpByHeaders',
593
+ key: 'invalidForwardedFor',
594
+ len: raw.length,
595
+ preview: safeText(raw.slice(0, FORWARDED_PREVIEW_LEN)),
596
+ ip: ipUsed,
597
+ suppressed,
598
+ })
599
+ if (r && isfun(r.catch)) {
600
+ r.catch(() => {})
601
+ }
602
+ }
603
+ catch (err) {
604
+ //診斷輸出失敗, 略過
605
+ }
606
+ }
607
+
608
+
609
+ //pickForwardedIp: X-Forwarded-For 之一段(已 trim 且非空)可否採用為來源 IP (R-IP-01, 單一擁有者), 回採用之 IP 或空字串:
610
+ // 合法 IP(isIP 為 4 或 6 且長度 ≤ FORWARDED_IP_MAX_LEN)→ 原字串, 不改寫(不剝 ::ffff:、不改大小寫、不去 zone; ips 表以原字串精確比對封鎖列, 改寫則既有列不再命中)
611
+ // 唯一之正規化: IPv4:port、[IPv6]:port 去 port 取 IP(部分雲端閘道於標頭帶來源 port; 退回連線位址則多層反代下全部使用者被視為同一閘道位址,
612
+ // 頻率限制與自動封鎖將誤封所有人), 去後之 IP 仍須通過上列檢查; 去後仍非 IP 或非此兩種形式者回空字串, 由呼叫端退回連線位址並記 warn
613
+ let pickForwardedIp = (raw) => {
614
+ let ip = raw
615
+ if (isIP(raw) === 0) {
616
+ ip = ''
617
+ let m4 = FORWARDED_RE_V4_PORT.exec(raw)
618
+ let m6 = FORWARDED_RE_V6_PORT.exec(raw)
619
+ let m = m4 || m6
620
+ if (m && Number(m[2]) <= FORWARDED_PORT_MAX && isIP(m[1]) === (m4 ? 4 : 6)) {
621
+ ip = m[1]
622
+ }
623
+ }
624
+ if (ip.length > FORWARDED_IP_MAX_LEN) {
625
+ return ''
626
+ }
627
+ return ip
628
+ }
629
+
630
+
485
631
  //getIpByHeaders
486
632
  let getIpByHeaders = (req) => {
487
633
 
@@ -504,11 +650,21 @@ function proc(woItems, p, opt = {}) {
504
650
  let ip = ''
505
651
 
506
652
  //x-forwarded-for, 內容為client, proxy1, proxy2,...要取第1個
653
+ //取得之值經 pickForwardedIp 須為合法 IP 才採用(原樣不改寫; 僅 IPv4:port、[IPv6]:port 去 port); 非 IP 者不採用, 由下列連線位址補上並限流記 warn (R-IP-01)
654
+ //信任邊界: 該標頭之真實性由最外層受信任之反向代理 / 防火牆保證, 本套件不做防偽造, 維持取最左段之語意 (使用者 2026-10-20 裁示)
655
+ let ipInvalid = ''
507
656
  if (!isestr(ip)) {
508
657
  let c = get(headers, 'x-forwarded-for', '')
509
658
  let s = sep(c, ',')
510
659
  ip = get(s, 0, '')
511
660
  ip = trim(ip)
661
+ if (isestr(ip)) {
662
+ let ipPicked = pickForwardedIp(ip)
663
+ if (!isestr(ipPicked)) {
664
+ ipInvalid = ip
665
+ }
666
+ ip = ipPicked
667
+ }
512
668
  }
513
669
 
514
670
  //info.remoteAddress
@@ -535,6 +691,11 @@ function proc(woItems, p, opt = {}) {
535
691
  }
536
692
  }
537
693
 
694
+ //標頭值非 IP: 已退回連線位址, 限流記 warn
695
+ if (ipInvalid !== '') {
696
+ warnInvalidForwardedFor(ipInvalid, ip)
697
+ }
698
+
538
699
  //logshow, 只印標頭名稱: 標頭值含 authorization(Bearer 權杖)、帶 ?token= 之 referer 等憑證 (ADR-068)
539
700
  if (!isestr(ip)) {
540
701
  console.log('headers(keys)', Object.keys(headers || {}))
@@ -630,7 +791,14 @@ function proc(woItems, p, opt = {}) {
630
791
 
631
792
  //blockIpByIp
632
793
  // blockIpByIp 由 timer 單一 caller 觸發, pmSeries 保證序列化, 無 race; 詳 audit F-052 verifier 結論
794
+ // (計時器之間互不競態, 但與後台 IP 清單存檔 / 計時器登錄新 IP 並行: 讀取與寫入整段在 ips 表鎖內, 規格 §7; S17 / S18)
633
795
  let blockIpByIp = async (ip) => {
796
+ return await withTabLocks(['ips'], () => _blockIpByIp(ip))
797
+ }
798
+
799
+
800
+ //_blockIpByIp, 須於 ips 表鎖內呼叫
801
+ let _blockIpByIp = async (ip) => {
634
802
  let errTemp = null
635
803
 
636
804
  //genTimeBlocked
@@ -676,8 +844,8 @@ function proc(woItems, p, opt = {}) {
676
844
  })
677
845
  // console.log('funNew', oip)
678
846
 
679
- //insert
680
- await woItems.ips.insert(oip)
847
+ //insert, 經 procOrm 戳記更新者 'system' (R-CONC-04)
848
+ await procOrm(SYSTEM_ID, 'ips', 'insert', [oip])
681
849
  .catch((err) => {
682
850
  errTemp = err
683
851
  })
@@ -703,12 +871,12 @@ function proc(woItems, p, opt = {}) {
703
871
  let timeBlocked = genTimeBlocked()
704
872
  // console.log('timeBlocked', timeBlocked)
705
873
 
706
- //封鎖ip, 須更新ip的timeBlocked; 逐筆檢查 (ADR-080)
874
+ //封鎖ip, 須更新ip的timeBlocked; 經 procOrm 且 mustExist(只改不增), 更新者記 'system'; 逐筆檢查 (ADR-080)
707
875
  let errSave = null
708
- await ormWrite(woItems.ips, 'save', {
876
+ await procOrm(SYSTEM_ID, 'ips', 'save', [{
709
877
  id: oip.id,
710
878
  timeBlocked,
711
- })
879
+ }], { mustExist: true })
712
880
  .catch((err) => {
713
881
  errSave = err
714
882
  })
@@ -756,16 +924,18 @@ function proc(woItems, p, opt = {}) {
756
924
 
757
925
 
758
926
  //timer, 偵測新ip出現儲存至ips; 讀取或新增失敗由 wrapTimer 記錄(timer-error), 下一輪重試(原讀取失敗時重入鎖不釋放而永久停擺, ADR-085)
759
- setInterval(wrapTimer('ipDetectNew', async () => {
760
-
761
- //ips, 鍵為使用端可植入之字串 (X-Forwarded-For), 以自有鍵取得 (R-KEY-01 / R-OBJ-ITER-01)
762
- let ips = Object.keys(kpIpCallApi)
763
- // console.log('ips', ips)
927
+ //讀取已登錄 IP 清單、比對與新增整段在 ips 表鎖內(S19): 與後台 IP 清單存檔、自動封鎖寫入互斥; 載入後才登錄之 IP 使持舊畫面存檔者被拒(先動先贏), 不致被整表存檔刪除 (X4)
928
+ setInterval(wrapTimer('ipDetectNew', () => withTabLocks(['ips'], async () => {
764
929
 
765
930
  //getIpsList
766
931
  let oips = await p.getIpsList()
767
932
  // console.log('oips', oips)
768
933
 
934
+ //ips, 鍵為使用端可植入之字串 (X-Forwarded-For), 以自有鍵取得 (R-KEY-01 / R-OBJ-ITER-01);
935
+ //於讀完 ips 清單後才取鍵: 讀取等待期間已被剪枝刪除之鍵不再登錄 (R-CNT-01), 同期新出現者一併登錄
936
+ let ips = Object.keys(kpIpCallApi)
937
+ // console.log('ips', ips)
938
+
769
939
  //kpIpOld
770
940
  let kpIpOld = mkKp()
771
941
  each(oips, (oip) => {
@@ -801,10 +971,12 @@ function proc(woItems, p, opt = {}) {
801
971
  })
802
972
  // console.log('oipsNew', oipsNew)
803
973
 
804
- //insert
805
- await woItems.ips.insert(oipsNew)
974
+ //insert, 經 procOrm 戳記更新者 'system' (R-CONC-04); 無新 IP 時不呼叫
975
+ if (size(oipsNew) > 0) {
976
+ await procOrm(SYSTEM_ID, 'ips', 'insert', oipsNew)
977
+ }
806
978
 
807
- }, timerError), 2000)
979
+ }), timerError), 2000)
808
980
 
809
981
 
810
982
  //timer, 限制ip最大調用API次數
@@ -817,14 +989,14 @@ function proc(woItems, p, opt = {}) {
817
989
  //偵測ip調用API次數
818
990
  await pmSeries(kpIpCallApi, async (times, ip) => {
819
991
 
820
- //recs, 提取指定時間範圍內的紀錄
821
- let recs = times.filter((timeRec) => {
822
- return timeRec >= timeStart //ot(t).isAfter(timeStart)
823
- })
992
+ //recs, 提取指定時間範圍內的紀錄, 並更新容器: 僅保留指定時間範圍內的紀錄, 窗內無紀錄則刪除該鍵 (pruneKpKey, R-CNT-01)
993
+ let recs = pruneKpKey(kpIpCallApi, ip, times, timeStart)
824
994
  // console.log(ip, 'recs', recs)
825
995
 
826
- //更新, 僅保留指定時間範圍內的紀錄
827
- kpIpCallApi[ip] = recs
996
+ //容器或該鍵已被換掉 (times 為舊快照, 例: 計時器等待前一鍵之封鎖寫入時 cleanKpIpCallApi 清空計數): 略過本鍵, 不據舊紀錄封鎖
997
+ if (recs === null) {
998
+ return
999
+ }
828
1000
 
829
1001
  //nrecs
830
1002
  let nrecs = size(recs)
@@ -847,6 +1019,16 @@ function proc(woItems, p, opt = {}) {
847
1019
  }, timerError), 2000)
848
1020
 
849
1021
 
1022
+ //getKpKeyCounts: 三個計數容器目前之鍵數 (診斷用; 例: 確認剪枝後鍵確實退場, R-CNT-01)
1023
+ let getKpKeyCounts = async () => {
1024
+ return {
1025
+ accountLoginFailed: Object.keys(kpAccountLoginFailed).length,
1026
+ tokenCallApi: Object.keys(kpTokenCallApi).length,
1027
+ ipCallApi: Object.keys(kpIpCallApi).length,
1028
+ }
1029
+ }
1030
+
1031
+
850
1032
  //pp
851
1033
  let pp = {
852
1034
 
@@ -854,6 +1036,7 @@ function proc(woItems, p, opt = {}) {
854
1036
 
855
1037
  cleanKpAccountLoginFailed,
856
1038
  cleanKpIpCallApi,
1039
+ getKpKeyCounts,
857
1040
 
858
1041
  // getEndByToken, //等同於p._checkToken(此未提供外部使用), 類似p.checkToken(resolve只回傳true, reject代表無效token與錯誤)
859
1042
  getBlockedByAccount,