w-web-perm 1.1.11 → 1.1.13

package/server/tools/authRefsAudit.mjs

@@ -0,0 +1,175 @@
+//懸空引用之離線稽核工具(適用表 n 上線後之升版前盤點; 規則帳本 R-REF-CASCADE-01 之配套; 不屬測試, 只讀匯出檔、不寫庫).
+//
+//用法(自專案根; 套件安裝後此檔位於 node_modules/w-web-perm/server/tools/, 以該路徑執行即可, 匯出檔路徑相對於目前工作目錄):
+//  node server/tools/authRefsAudit.mjs <匯出檔.json> [--json] [--clean-out <檔>]
+//
+//  匯出檔內容 { users, grups, pemis, targets }(各為列陣列, 如以資料通道 select 之結果或 g_backupDb.mjs 之備份整理而得)。
+//  --json       輸出結構化結果 { items, counts, changes, badJson, unnamed, unsafe, noId, widen }(供其他工具), 省略則輸出文字報告.
+//  --clean-out  把「清理後之引用端列」(僅變更者之主鍵 id 與新字串)寫成 json 供審閱: { users: [{ id, cgrups }], grups: [{ id, cpemis }], pemis: [{ id, crules }] }.
+//
+//報告內容:
+//  1. 懸空引用清單(users.cgrups 引用不存在之群組名、grups.cpemis 引用不存在之權限名、pemis.crules 引用不存在之管控對象 id): 逐引用端列出被引用之名稱、isActive、mode 與對授權之影響.
+//  2. 清理後授權可能變多之使用者／群組數(啟用之 AND 懸空項使結果為空, 清理後限制解除; 含「唯一 OR 項」與經群組傳導之情形).
+//  3. 壞 JSON(解析失敗, 視為無引用, 不處理)清單、名稱非字串之引用(不處理, 須人工)清單.
+//  4. 建議處置步驟.
+//  不回顯 email／name 等個資(只列主鍵 id 與被引用之名稱).
+//
+//清理由 g_authRefsClean.mjs 執行(預設只列不改, 加 --apply 才寫入; 寫入前備份); 解析與改寫邏輯同 src/js/refAudit.mjs(改寫經 src/js/refCascade.mjs 之 rewriteRefs).
+
+import fs from 'fs'
+import path from 'path'
+import isMain from './isMain.mjs'
+import auditRefs, { EFFECT } from '../../src/js/refAudit.mjs'
+
+
+const TABLE_LABEL = { users: 'users.cgrups(引用群組名)', grups: 'grups.cpemis(引用權限名)', pemis: 'pemis.crules(引用管控對象 id)' }
+const TARGET_LABEL = { users: '群組', grups: '權限', pemis: '管控對象' }
+const BAD_TXT = { parse: 'JSON5 解析失敗', notContainer: '解析結果非物件／陣列', decode: '解碼失敗' }
+const MAX_HOLDERS = 500 //文字報告每表最多列出之引用端列數(完整請用 --json)
+
+
+let arr = (v) => (Array.isArray(v) ? v : [])
+let j = (v) => JSON.stringify(v)
+
+
+/**
+ * 建立稽核結果(純函數, 不讀寫檔案): auditRefs 之結果加上各表筆數
+ *
+ * @param {Object} data { users, grups, pemis, targets }
+ * @returns {Object} 稽核結果
+ */
+function buildReport(data) {
+    let d = (data !== null && typeof data === 'object') ? data : {}
+    let rp = auditRefs(d)
+    return {
+        rows: { users: arr(d.users).length, grups: arr(d.grups).length, pemis: arr(d.pemis).length, targets: arr(d.targets).length },
+        ...rp,
+    }
+}
+
+
+/**
+ * 清理後之引用端列(供 --clean-out): 僅變更者之主鍵 id 與新字串, 即 ORM save 之輸入形狀
+ *
+ * @param {Array} changes auditRefs 之 changes
+ * @returns {Object} { users: [{ id, cgrups }], grups: [{ id, cpemis }], pemis: [{ id, crules }] }
+ */
+function cleanOutOf(changes) {
+    let out = { users: [], grups: [], pemis: [] }
+    for (let c of arr(changes)) {
+        out[c.table].push({ id: c.id, [c.field]: c.after })
+    }
+    return out
+}
+
+
+//formatReport: 結果轉文字
+function formatReport(rp, opt = {}) {
+    let maxHolders = Number.isInteger(opt.maxHolders) ? opt.maxHolders : MAX_HOLDERS
+    let c = rp.counts
+    let L = []
+    L.push(`資料筆數: users ${rp.rows.users}、grups ${rp.rows.grups}、pemis ${rp.rows.pemis}、targets ${rp.rows.targets}`)
+    L.push('')
+    L.push(`== 懸空引用(引用之名稱查無實體): 共 ${c.nItems} 項, 涉及引用端 ${c.byTable.users.nHolders + c.byTable.grups.nHolders + c.byTable.pemis.nHolders} 列; 清理後會改寫 ${c.nChanges} 列 ==`)
+    for (let t of ['users', 'grups', 'pemis']) {
+        let its = rp.items.filter((x) => x.table === t)
+        let bt = c.byTable[t]
+        L.push(`-- ${TABLE_LABEL[t]}: ${bt.nItems} 項, ${bt.nHolders} 列`)
+        let byHolder = new Map()
+        for (let x of its) {
+            if (!byHolder.has(x.holderId)) {
+                byHolder.set(x.holderId, [])
+            }
+            byHolder.get(x.holderId).push(x)
+        }
+        let n = 0
+        for (let [id, xs] of byHolder) {
+            if (n++ >= maxHolders) {
+                L.push(`   …(其餘 ${byHolder.size - maxHolders} 列從略, 完整清單請加 --json)`)
+                break
+            }
+            let txt = xs.map((x) => `${j(x.name)}${t === 'pemis' ? '' : `(${x.isActive === 'y' ? '啟用' : '停用'}, mode=${j(x.mode)})`}`).join('、')
+            L.push(`   ${t} id=${id}: ${txt}`)
+        }
+    }
+    L.push('')
+    L.push(`== 對授權之影響(ref 類之 cgrups／cpemis; crules 懸空項不影響授權) ==`)
+    L.push(`- 啟用之懸空項 ${c.nActive} 項(其中有效模式為 AND 者 ${c.nAndActive} 項、OR 者 ${c.nOrActive} 項), 停用之懸空項 ${c.nInactive} 項`)
+    L.push(`- 擁有「啟用 AND 懸空項」之使用者 ${c.byTable.users.nAndActiveHolders} 位、群組 ${c.byTable.grups.nAndActiveHolders} 個: 現況其授權(該層合併結果)被收嚴為空; 清理後 AND 限制解除, 授權可能變多`)
+    L.push(`- 清理後授權可能變多(含唯一 OR 懸空項而同層有合法 AND 項、經群組傳導者): 使用者 ${c.nWidenUsers} 位、群組 ${c.nWidenGrups} 個`)
+    for (let w of rp.widen.slice(0, maxHolders)) {
+        L.push(`   ${w.table} id=${w.holderId}${w.via === 'grups' ? '(經其啟用引用之群組傳導)' : ''}`)
+    }
+    if (rp.widen.length > maxHolders) {
+        L.push(`   …(其餘 ${rp.widen.length - maxHolders} 筆從略, 完整清單請加 --json)`)
+    }
+    L.push('- 影響說明:')
+    L.push(`   AND: ${EFFECT.and}`)
+    L.push(`   OR: ${EFFECT.or}`)
+    L.push(`   停用: ${EFFECT.inactive}`)
+    L.push(`   crules: ${EFFECT.rule}`)
+    L.push('')
+    L.push(`== 授權字串壞 JSON(解析失敗等, 視為無引用, 清理時不處理): ${rp.badJson.length} 列 ==`)
+    rp.badJson.forEach((b) => L.push(`- ${b.table} id=${b.id} 欄位 ${b.field}: ${BAD_TXT[b.reason] || b.reason}`))
+    L.push('')
+    L.push(`== 名稱非字串之引用(陣列元素無 name 等, 不對應任何${TARGET_LABEL.users}／${TARGET_LABEL.grups}名, 清理時不處理, 須人工於後台修正): ${rp.unnamed.length} 項 ==`)
+    rp.unnamed.slice(0, maxHolders).forEach((x) => L.push(`- ${x.table} id=${x.holderId} 欄位 ${x.field} isActive=${j(x.isActive)} mode=${j(x.mode)}`))
+    if (rp.unsafe && rp.unsafe.length > 0) {
+        L.push(`== 含無法安全重新編碼之內容(JSON5 Infinity／NaN 數值)而不清理之授權欄位, 須人工處理: ${rp.unsafe.length} 項 ==`)
+        rp.unsafe.slice(0, maxHolders).forEach((x) => L.push(`- ${x.table} id=${x.id} 欄位 ${x.field}`))
+    }
+    if (rp.noId.length > 0) {
+        L.push('')
+        L.push(`== 缺字串主鍵而無從寫回之引用端列: ${rp.noId.length} 列(不清理) ==`)
+        rp.noId.forEach((x) => L.push(`- ${x.table} id=${j(x.holderId)} 欄位 ${x.field}: ${x.nItems} 項懸空`))
+    }
+    L.push('')
+    L.push('== 建議處置步驟 ==')
+    L.push('1. 先確認本報告「對授權之影響」: 啟用 AND 懸空項若本意為限制(例如曾刪除群組／權限而期望該使用者從此無授權), 清理會使其授權變多; 此類請先於後台改正名稱(或停用該引用)再清理.')
+    L.push('2. 預設只列不改: node g_authRefsClean.mjs(連專案資料庫, 與本報告同一判準); 確認清單後再加 --apply 寫入(寫入前自動備份資料庫與將改寫之三張引用端表, 任一備份失敗即中止).')
+    L.push('3. 建議於停服(或無人編輯)時執行 --apply, 執行後重啟服務(避免伺服端快取沿用舊字串), 並以 getPerm／getPermUserInfor 抽查數位使用者之授權.')
+    L.push('4. 寫入後工具會重新稽核, 應為 0 懸空; 壞 JSON 與名稱非字串者不受清理影響, 須另行處理.')
+    return L.join('\n')
+}
+
+
+//CLI
+if (isMain(import.meta.url)) {
+    let args = process.argv.slice(2)
+    let iOut = args.indexOf('--clean-out')
+    let cleanOut = (iOut >= 0) ? args[iOut + 1] : undefined
+    let fp = args.find((a, k) => !a.startsWith('--') && !(iOut >= 0 && k === iOut + 1))
+    if (!fp || (iOut >= 0 && (cleanOut === undefined || cleanOut.startsWith('--')))) {
+        console.log('用法: node server/tools/authRefsAudit.mjs <匯出檔.json> [--json] [--clean-out <檔>]')
+        process.exit(2)
+    }
+    //輸出不得覆寫輸入(同一檔; 以解析後之絕對路徑與已存在檔之 inode 判定): --clean-out 只含變更列之 id 與引用欄位, 覆寫匯出檔會使其遺失其餘列與欄位
+    if (cleanOut !== undefined) {
+        let same = path.resolve(fp).toLowerCase() === path.resolve(cleanOut).toLowerCase()
+        if (!same && fs.existsSync(cleanOut) && fs.existsSync(fp)) {
+            let a = fs.statSync(fp)
+            let b = fs.statSync(cleanOut)
+            same = a.ino !== 0 && a.ino === b.ino && a.dev === b.dev
+        }
+        if (same) {
+            console.error('失敗: --clean-out 不得與輸入匯出檔為同一檔(會覆寫原匯出檔)')
+            process.exit(2)
+        }
+    }
+    try {
+        let data = JSON.parse(fs.readFileSync(fp, 'utf8'))
+        let rp = buildReport(data)
+        console.log(args.includes('--json') ? JSON.stringify(rp, null, 1) : formatReport(rp))
+        if (cleanOut !== undefined) {
+            fs.writeFileSync(cleanOut, JSON.stringify(cleanOutOf(rp.changes), null, 1), 'utf8')
+            console.error(`已寫入清理後之引用端列(僅變更者): ${cleanOut}`) //stderr: 不污染 --json 之 stdout
+        }
+    }
+    catch (err) {
+        console.error(`失敗: ${err && err.message ? err.message : err}`)
+        process.exitCode = 1
+    }
+}
+
+
+export { buildReport, formatReport, cleanOutOf }

package/server/tools/authRefsClean.mjs

@@ -0,0 +1,263 @@
+//懸空引用之一次性清理(升版工具; 規則帳本 R-REF-CASCADE-01 之配套): 稽核 users.cgrups／grups.cpemis／pemis.crules 中查無實體之引用, 預設只列不改, apply 時才寫入.
+//由專案根之 g_authRefsClean.mjs 呼叫(連專案資料庫); 邏輯抽成可注入 woItems 之函數, 供單元測試以臨時資料庫驗證(test/unit-refAudit.test.mjs).
+//
+//apply 之順序(任一步失敗即中止, 其後之步驟不執行; 備份失敗時零寫入):
+//  1. 讀取四表並稽核(src/js/refAudit.mjs); 無須清理者不備份、不寫入
+//  2. (a) 備份整個資料庫(getDb.backup(woItems), 落點為模組載入時之工作目錄之 backup-時間.json, 同 g_backupDb.mjs; 可由 backupDb 注入)
+//  3. (b) 另匯出將被改寫之三張引用端表(users／grups／pemis)全部列(並附 targets 供稽核重現)為 json(backupPath; 不覆寫既有檔), 寫後讀回驗證
+//  4. 重新讀取引用端表, 逐筆確認 before 仍等於庫內現值(稽核後被他人改動者中止, 免以過期資料覆蓋)
+//  5. 寫入: woItems[表].save([{ id, [欄位]: 新字串 }], { autoInsert: false })——只改該欄位, 列已不存在時不得補出只有一欄之殘列; 逐筆結果 ok 非 1、n 為 0 或有 nInserted 者視為失敗並列出
+//  6. 重新讀取並稽核: 懸空須為 0、變更之列只有該欄位改變、其餘列逐位元不變, 否則視為失敗
+//     例外(已知殘留, 非失敗): 含無法安全重新編碼之內容(JSON5 Infinity／NaN, 重新編碼會變成 null 而改指別的規則名; 見 refCascade.rewriteRefs 之 unsafe)之授權欄位不清理,
+//     其懸空項目寫前寫後皆在, 逐筆須與寫前相同(多或少即失敗), 並於報告列為「須人工處理」(res.unsafe／res.residue)
+//備份檔路徑: 以 flag wx 建立(同名既有檔、同一檔之別名——大小寫不同、相對／絕對、硬連結——一律拒絕、不覆寫, 失敗於 backupRows 階段、零寫入)
+//備份檔含 email 等個資, 請妥善保管、勿外傳、勿納入版控.
+
+import fs from 'fs'
+import path from 'path'
+import { isDeepStrictEqual } from 'util'
+import getDb from 'w-serv-orm/src/getDb.mjs'
+import now2strp from 'wsemi/src/now2strp.mjs'
+import { buildReport, formatReport } from './authRefsAudit.mjs'
+import { isJsonLossy } from './fromTools.mjs'
+
+
+const TABLES = ['users', 'grups', 'pemis', 'targets']
+const HOLDERS = ['users', 'grups', 'pemis']
+
+
+let arr = (v) => (Array.isArray(v) ? v : [])
+let msgOf = (err) => (err && err.message ? err.message : String(err))
+let byId = (rows) => new Map(arr(rows).map((r) => [r.id, r]))
+
+
+//readTables: 讀取四表全部列
+async function readTables(woItems) {
+    let rows = {}
+    for (let t of TABLES) {
+        let rs = await woItems[t].select()
+        if (!Array.isArray(rs)) {
+            throw new Error(`select ${t} did not return an array`)
+        }
+        rows[t] = rs
+    }
+    return rows
+}
+
+
+/**
+ * 稽核並(apply 時)清理懸空引用
+ *
+ * @param {Object} p 輸入參數物件
+ * @param {Object} p.woItems 輸入 ORM 資料表物件(users、grups、pemis、targets 各有 select／save)
+ * @param {Boolean} [p.apply=false] 輸入是否寫入, 預設 false(只列不改)
+ * @param {String} [p.backupPath] 輸入引用端表之備份檔路徑, 預設 ./authRefsClean-backup-<時間戳>.json(相對工作目錄)
+ * @param {Function} [p.backupDb] 輸入資料庫備份函數(回傳 Promise, reject 表失敗), 預設 getDb.backup(woItems)
+ * @param {Function} [p.log] 輸入輸出文字之函數, 預設 console.log
+ * @returns {Promise<Object>} 回傳 { ok, apply, stage, err, audit, auditAfter, dbBackup, backupPath, written, failed, stale }; ok 為 false 時 stage 為失敗之階段(check／select／backupFidelity／backupDb／backupRows／stale／write／verify), err 為訊息; 不 reject
+ */
+async function runClean(p = {}) {
+    let woItems = p.woItems
+    let apply = p.apply === true
+    let log = typeof p.log === 'function' ? p.log : console.log
+    let backupDb = typeof p.backupDb === 'function' ? p.backupDb : () => getDb.backup(woItems)
+    let res = { ok: false, apply, stage: 'check', err: '', audit: null, auditAfter: null, dbBackup: false, backupPath: '', written: [], failed: [], stale: [], unsafe: [], residue: [] }
+    let fail = (stage, err) => {
+        res.ok = false
+        res.stage = stage
+        res.err = msgOf(err)
+        log(`失敗(階段 ${stage}): ${res.err}`)
+        if (res.written.length > 0 || res.failed.length > 0) {
+            log(`已寫入 ${res.written.length} 列, 失敗 ${res.failed.length} 列${res.failed.length > 0 ? ': ' + res.failed.map((f) => `${f.table} id=${f.id}(${f.err})`).join('; ') : ''}; 請依備份檔還原或重跑本工具`)
+        }
+        return res
+    }
+
+    //check
+    if (woItems === null || typeof woItems !== 'object') {
+        return fail('check', 'invalid woItems')
+    }
+    for (let t of TABLES) {
+        if (!woItems[t] || typeof woItems[t].select !== 'function' || (apply && typeof woItems[t].save !== 'function')) {
+            return fail('check', `woItems.${t} lacks select${apply ? '／save' : ''}`)
+        }
+    }
+
+    //select, audit
+    let rows0 = null
+    try {
+        rows0 = await readTables(woItems)
+    }
+    catch (err) {
+        return fail('select', err)
+    }
+    let rp = buildReport(rows0)
+    res.audit = rp
+    res.unsafe = rp.unsafe
+    log(formatReport(rp))
+    let unsafeNote = rp.unsafe.length > 0 ? `另有 ${rp.unsafe.length} 個授權欄位含無法安全重新編碼之內容(JSON5 Infinity／NaN), 本工具不清理(其懸空項目仍在), 須人工處理: ${rp.unsafe.map((u) => `${u.table} id=${u.id}`).join('、')}` : ''
+    if (!apply) {
+        log('')
+        log('(預設只列不改; 確認清單後加 --apply 才寫入, 寫入前會自動備份)')
+        res.ok = true
+        res.stage = 'audit'
+        return res
+    }
+    if (rp.changes.length === 0) {
+        log('')
+        log('無須清理(沒有可改寫之懸空引用), 不備份、不寫入.')
+        if (unsafeNote !== '') {
+            log(unsafeNote)
+        }
+        res.ok = true
+        res.stage = 'audit'
+        return res
+    }
+
+    //備份保真(run08 外審 sol #2, 與 fromTools.backupBefore 同一判準 isJsonLossy): 引用端表備份為 JSON, NaN／±Infinity／bigint／Date／undefined／Buffer 等非 JSON 值會被存成 null 或別型,
+    //依備份還原即遺失原值而筆數回驗不會發現; 列內含此類值時於任何備份與寫入之前中止(零寫入), 須人工處理該列
+    res.stage = 'backupFidelity'
+    for (let t of TABLES) {
+        if (isJsonLossy(rows0[t])) {
+            return fail('backupFidelity', `backup would be lossy: table ${t} has a row that does not survive a JSON round trip (NaN, Infinity, bigint, Date, undefined, Buffer...); nothing was written. Please fix that row first`)
+        }
+    }
+
+    //(a) 備份整個資料庫
+    res.stage = 'backupDb'
+    try {
+        await backupDb()
+        res.dbBackup = true
+    }
+    catch (err) {
+        return fail('backupDb', err)
+    }
+
+    //(b) 匯出引用端表全部列
+    res.stage = 'backupRows'
+    try {
+        let fp = path.resolve(p.backupPath || `./authRefsClean-backup-${now2strp()}.json`)
+        res.backupPath = fp
+        let body = { meta: { tool: 'authRefsClean', time: new Date().toISOString(), note: 'users／grups／pemis 為將被改寫之引用端表之全部列(寫入前); targets 未被改寫, 附上供稽核重現. 含個資, 請妥善保管.' } }
+        for (let t of TABLES) {
+            body[t] = rows0[t]
+        }
+        let txt = JSON.stringify(body)
+        fs.writeFileSync(fp, txt, { encoding: 'utf8', flag: 'wx' }) //wx: 既有檔不覆寫
+        let back = JSON.parse(fs.readFileSync(fp, 'utf8'))
+        for (let t of TABLES) {
+            if (!Array.isArray(back[t]) || back[t].length !== rows0[t].length) {
+                throw new Error(`backup file verification failed: ${t}`)
+            }
+        }
+        log(`已備份: 資料庫(backup-時間.json, 於工作目錄)、引用端表全部列 ${fp}`)
+    }
+    catch (err) {
+        return fail('backupRows', err)
+    }
+
+    //稽核後被他人改動者中止
+    res.stage = 'stale'
+    let rows1 = null
+    try {
+        rows1 = await readTables(woItems)
+    }
+    catch (err) {
+        return fail('stale', err)
+    }
+    for (let c of rp.changes) {
+        let r = byId(rows1[c.table]).get(c.id)
+        if (r === undefined || r[c.field] !== c.before) {
+            res.stale.push({ table: c.table, id: c.id })
+        }
+    }
+    if (res.stale.length > 0) {
+        return fail('stale', `${res.stale.length} rows changed or removed since the audit: ${res.stale.slice(0, 10).map((s) => `${s.table} id=${s.id}`).join(', ')}`)
+    }
+
+    //write
+    res.stage = 'write'
+    for (let t of HOLDERS) {
+        let cs = rp.changes.filter((c) => c.table === t)
+        if (cs.length === 0) {
+            continue
+        }
+        let rs = null
+        try {
+            rs = await woItems[t].save(cs.map((c) => ({ id: c.id, [c.field]: c.after })), { autoInsert: false })
+        }
+        catch (err) {
+            cs.forEach((c) => res.failed.push({ table: t, id: c.id, err: msgOf(err) }))
+            continue
+        }
+        if (!Array.isArray(rs) || rs.length !== cs.length) {
+            cs.forEach((c) => res.failed.push({ table: t, id: c.id, err: 'unexpected save result' }))
+            continue
+        }
+        cs.forEach((c, k) => {
+            let r = rs[k]
+            if (r && r.ok === 1 && r.n !== 0 && !(r.nInserted > 0)) {
+                res.written.push({ table: t, id: c.id })
+            }
+            else {
+                res.failed.push({ table: t, id: c.id, err: (r && r.err) ? String(r.err) : `save result ${JSON.stringify(r)}` })
+            }
+        })
+    }
+    if (res.failed.length > 0) {
+        return fail('write', `${res.failed.length} rows failed to save`)
+    }
+
+    //verify: 重新稽核須為 0 懸空, 變更之列只有該欄位改變, 其餘列逐位元不變
+    res.stage = 'verify'
+    try {
+        let rows2 = await readTables(woItems)
+        res.auditAfter = buildReport(rows2)
+        let newOf = new Map(rp.changes.map((c) => [`${c.table}\u0000${c.id}`, c]))
+        let bad = []
+        for (let t of HOLDERS) {
+            let m0 = byId(rows0[t])
+            let m2 = byId(rows2[t])
+            if (m2.size !== m0.size || rows2[t].length !== rows0[t].length) {
+                bad.push(`${t} row count ${rows0[t].length} -> ${rows2[t].length}`)
+                continue
+            }
+            for (let [id, r0] of m0) {
+                let c = newOf.get(`${t}\u0000${id}`)
+                let expect = c ? { ...r0, [c.field]: c.after } : r0
+                if (!isDeepStrictEqual(m2.get(id), expect)) {
+                    bad.push(`${t} id=${id}`)
+                }
+            }
+        }
+        if (bad.length > 0) {
+            return fail('verify', `rows differ from expected after write: ${bad.slice(0, 10).join(', ')}`)
+        }
+        //已知殘留: 含無法安全重新編碼之內容(unsafe)之列不清理, 其懸空項目於寫前寫後皆在(須人工處理); 除此之外不得有懸空
+        let unsafeKeys = new Set(rp.unsafe.map((u) => `${u.table}\u0000${u.id}`))
+        res.residue = rp.items.filter((x) => unsafeKeys.has(`${x.table}\u0000${x.holderId}`))
+        let rest = res.auditAfter.items.filter((x) => !unsafeKeys.has(`${x.table}\u0000${x.holderId}`))
+        if (rest.length !== 0) {
+            return fail('verify', `${rest.length} dangling refs remain after clean`)
+        }
+        if (!isDeepStrictEqual(res.auditAfter.items, res.residue)) {
+            return fail('verify', 'residue of unsafe rows changed unexpectedly')
+        }
+    }
+    catch (err) {
+        return fail('verify', err)
+    }
+
+    res.ok = true
+    res.stage = 'done'
+    let n = (t) => res.written.filter((w) => w.table === t).length
+    log('')
+    log(`已清理: 寫入 ${res.written.length} 列(users ${n('users')}、grups ${n('grups')}、pemis ${n('pemis')}); 重新稽核懸空 ${res.auditAfter.items.length} 項${res.residue.length > 0 ? `(皆為下述不清理之列的既知殘留, 非錯誤)` : ''}. 請重啟服務並抽查授權.`)
+    if (unsafeNote !== '') {
+        log(unsafeNote)
+    }
+    return res
+}
+
+
+export { runClean, TABLES }