RN-Pro-Inspector

Debug overlay Network · Redux · Console · Storage cho React Native. Overlay nổi kéo-thả, mở khoá bằng mật khẩu (SHA-256) ngay trên màn đăng nhập của app, có data masking và ring buffer chống tràn RAM.

Mặc định TẮT hoàn toàn — không render, không patch fetch/XHR, không log (zero overhead). Chỉ khi nhập đúng mật khẩu ở màn login thì tool mới bật. Vì đã chặn bằng pass nên bật được cả trên production.

📖 Bản HTML đẹp (đi kèm trong package): docs/guide.html

Sau khi publish lên npm, file HTML này sẽ được đóng gói cùng gói package để người dùng có thể mở trực tiếp từ thư mục cài đặt.

Tính năng

| Tab | Nội dung | |-----|----------| | Network | Bắt mọi fetch & XHR: method, status, thời gian, size. Lọc nhanh (Lỗi / method), tìm trong cả body, copy cURL kiểu Postman, ghim ★. | | Redux | Log action + payload, xem diff state và state hiện thời, copy action. | | Console | Bắt console.log/info/warn/error + JS error toàn cục. Lọc theo mức, tìm kiếm. | | Storage | Xem / tìm / copy / xoá key trong AsyncStorage (tự parse JSON). | | Settings | Toggle Dark/Light, tạm dừng ghi log, ghi Redux state, mask keys, tiện ích app. |

Thao tác nhanh: ấn giữ 1 dòng để copy · ghim ★ giữ log khỏi bị đẩy trôi · giữ nút nổi mở menu nhanh.

Cài đặt

npm i rn-pro-inspector

Peer dependencies:

| Package | Bắt buộc? | Dùng cho | |---------|-----------|----------| | react, react-native | ✅ | Lõi | | @reduxjs/toolkit / redux | tuỳ chọn | inspectorMiddleware | | @react-native-clipboard/clipboard | tuỳ chọn | Nút Copy / cURL | | @react-native-async-storage/async-storage | tuỳ chọn | Tab Storage |

Dùng local (chưa publish): thêm "rn-pro-inspector": "file:./rn-pro-inspector" vào package.json, hoặc babel alias 'rn-pro-inspector' → './rn-pro-inspector/src'.

Tích hợp — đúng 3 điểm

Gỡ lúc nào cũng dễ: npm uninstall + xoá 3 chỗ dưới.

1) Mount <InspectorRoot> ở gốc App

import { InspectorRoot } from 'rn-pro-inspector';

// Render null cho tới khi mở khoá.
<InspectorRoot
  config={{
    passwordHash: '<sha256 của mật khẩu>',
    maskKeys: ['password', 'token', 'authorization'],
  }}
/>;

2) Cắm middleware vào Redux store (no-op tới khi mở khoá)

import { inspectorMiddleware } from 'rn-pro-inspector';

configureStore({
  reducer,
  middleware: (getDefaultMiddleware) => getDefaultMiddleware().concat(inspectorMiddleware),
});

3) Mở khoá ở màn đăng nhập

import { InspectorGate } from 'rn-pro-inspector';

// Khi người dùng gõ mật khẩu (tryUnlock chỉ so hash -> gọi mỗi ký tự vẫn an toàn):
useEffect(() => {
  if (password) InspectorGate.tryUnlock(password);
}, [password]);

Gõ đúng pass → nút nổi RPI hiện lên → chạm để mở dashboard. Sai/không biết → không thấy gì.

Tạo passwordHash

Không lưu mật khẩu thô — chỉ lưu SHA-256. Chạy 1 lần rồi dán hex vào config:

node -e "console.log(require('crypto').createHash('sha256').update('YOUR_PASSWORD').digest('hex'))"

Sai mật khẩu 5 lần → khoá 15 phút + dọn sạch RAM (chống brute-force).

Cấu hình (InspectorConfig)

| Field | Mặc định | Mô tả | |-------|----------|-------| | passwordHash (bắt buộc) | — | SHA-256 của mật khẩu mở khoá. | | enabled | true | false để tắt hẳn SDK. | | theme | 'light' | Theme khởi tạo; đổi runtime trong Settings. | | maskKeys | DEFAULT_MASK_KEYS | Key nhạy cảm bị che ***HIDDEN***. | | ignoreUrls | DEFAULT_IGNORE_URLS | URL bỏ qua khỏi Network (chuỗi chứa / RegExp). | | maxNetworkLogs | 100 | Sức chứa ring buffer Network. | | maxReduxLogs | 100 | Sức chứa ring buffer Redux. | | maxConsoleLogs | 200 | Sức chứa ring buffer Console. | | includeReduxState | false | Ghi prev/next state mỗi action (bật để xem diff). | | maxFailedAttempts | 5 | Số lần sai trước khi khoá. | | lockoutDurationMs | 900000 | Thời gian khoá (15 phút). | | customActions | [] | Nút tiện ích app trong Settings. |

customActions — tiện ích app

Cắm thao tác riêng của app vào Settings; tool render nút, logic do bạn cấp:

customActions: [
  { label: 'Xoá cache app', confirm: true, onPress: async () => {/* RNFS.unlink(...) */} },
  { label: 'Reset Redux', danger: true, confirm: true, onPress: async () => { await persistor.purge(); } },
];

InspectorAction: { label, description?, danger?, confirm?, onPress } — onPress hỗ trợ async.

Public API

import {
  InspectorRoot,            // component mount ở gốc App
  InspectorGate,            // tryUnlock(pw) / isActive() / lock()
  inspectorMiddleware,      // Redux middleware dựng sẵn
  createInspectorMiddleware,// factory tuỳ biến
  sha256,                   // sinh passwordHash
  DEFAULT_MASK_KEYS,
  DEFAULT_IGNORE_URLS,
} from 'rn-pro-inspector';

import type { InspectorConfig, InspectorAction, NetworkLogEntry, ReduxLogEntry } from 'rn-pro-inspector';

Mô hình bảo mật

• Mặc định TẮT → không render / không patch / không log. Zero overhead trên production.
• SHA-256 gate — chỉ lưu hash, không giữ plaintext.
• Chống brute-force — sai N lần → khoá + tự flush RAM.
• Data masking — đệ quy che field nhạy cảm trong payload/log.
• Memory guard — RingBuffer giữ RAM ở hằng số.
• Zero-crash — mọi interceptor bọc try-catch, không làm gãy app.

Dùng cho web React?

Không dùng thẳng — UI import primitive React Native (PanResponder, Animated, FlatList, Modal). Nhưng lõi (interceptor fetch/XHR, Redux middleware, RingBuffer, SecurityManager, sha256, buildCurl) chạy được trên trình duyệt.

• Nhanh: alias react-native → react-native-web + vá vài chỗ (ErrorUtils → window.onerror, AsyncStorage → localStorage).
• Sạch: tách @rn-pro-inspector/core dùng chung + UI React DOM riêng.

Scripts

| Lệnh | Mô tả | |------|-------| | npm run typecheck | Kiểm tra kiểu TypeScript | | npm test | Unit test (RingBuffer, SHA-256, SecurityManager) | | npm run prepublishOnly | Build (react-native-builder-bob) trước khi publish |

License

MIT