@onekeyfe/react-native-capture-protection 6.7.0-alpha.475 → 6.8.0-3

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.
package/README.md CHANGED
@@ -1,19 +1,54 @@
1
+ <div align="center">
2
+
1
3
  # @onekeyfe/react-native-capture-protection
2
4
 
3
- Permission-minimal capture protection for OneKey iOS and Android.
5
+ **Permission-minimal screenshot, recording and app-switcher protection for OneKey on iOS and Android.**
6
+
7
+ [![npm](https://img.shields.io/npm/v/%40onekeyfe%2Freact-native-capture-protection?label=npm&color=4D6BFE)](https://www.npmjs.com/package/@onekeyfe/react-native-capture-protection)
8
+ [![license](https://img.shields.io/npm/l/%40onekeyfe%2Freact-native-capture-protection?label=license&color=4D6BFE)](LICENSE)
9
+ ![iOS](https://img.shields.io/badge/iOS-000000?logo=apple&logoColor=white)
10
+ ![Android](https://img.shields.io/badge/Android-3DDC84?logo=android&logoColor=white)
11
+ ![Nitro Modules](https://img.shields.io/badge/Nitro_Modules-4D6BFE)
12
+
13
+ </div>
14
+
15
+ Protects wallet-sensitive screens without photo-library or filesystem access.
16
+ One call turns on screenshot, recording and app-switcher protection together, a
17
+ subscription reports capture-related native events, and `allow()` releases the
18
+ protection owned by that native object. This is deliberately a subset of the
19
+ upstream library: only `prevent()`, `allow()` and `addListener()` are exported,
20
+ and Web/desktop runtimes keep their own platform integration.
21
+
22
+ ## Features
23
+
24
+ - **One-call protection** — `prevent()` enables screenshot, recording and
25
+ app-switcher protection together; repeated calls are idempotent.
26
+ - **Typed capture events** — `CaptureEventType` reports captures, recordings,
27
+ app switching and protection-state changes without reading image contents.
28
+ - **Permission-minimal** — no photo-library or storage permission; Android only
29
+ adds the normal `DETECT_SCREEN_CAPTURE` permission for Android 14+ callbacks.
30
+ - **Fail-closed** — when the native registration, foreground window or secure
31
+ layer is unavailable, protection rejects instead of silently pretending the
32
+ screen is covered.
33
+ - **Scoped ownership** — protection belongs to a native object, so one owner's
34
+ `allow()` cannot release another owner's protection.
35
+ - **Lazy native object** — importing the wrapper performs no native work; the
36
+ hybrid object is created on first use.
4
37
 
5
38
  ## Installation
6
39
 
7
40
  ```sh
8
- yarn add @onekeyfe/react-native-capture-protection react-native-nitro-modules@0.37.0
41
+ yarn add @onekeyfe/react-native-capture-protection react-native-nitro-modules
9
42
  ```
10
43
 
11
- Install iOS pods and rebuild the native application. Web and desktop callers
12
- use their existing platform integration; this package has no implementation for
13
- those runtimes. Import is lazy, while a missing native registration throws when
14
- protection or a listener is requested.
44
+ Install the application's iOS pods and rebuild the native application; this is a
45
+ Nitro module, so a JavaScript-only install does not register it. The iOS pod also
46
+ links `ReactNativeNativeLogger`, so the application's pods must include
47
+ `@onekeyfe/react-native-native-logger`. Android's `DETECT_SCREEN_CAPTURE`
48
+ permission is declared by the package manifest for Android 14+; no `Info.plist`
49
+ key is required.
15
50
 
16
- ## Usage and cleanup
51
+ ## Usage
17
52
 
18
53
  ```ts
19
54
  import {
@@ -22,62 +57,88 @@ import {
22
57
  } from '@onekeyfe/react-native-capture-protection';
23
58
 
24
59
  await CaptureProtection.prevent();
60
+
25
61
  const subscription = CaptureProtection.addListener((event) => {
26
62
  if (event === CaptureEventType.CAPTURED) {
27
- /* Show a warning. */
63
+ // Show the application's own warning UI.
28
64
  }
29
65
  });
66
+
67
+ // Remove on unmount; this does not call allow().
30
68
  subscription.remove();
31
69
  await CaptureProtection.allow();
32
70
  ```
33
71
 
34
- Only the application's existing prevent/allow/listener API is supported.
35
- No photo-library or filesystem permission is declared or requested.
36
- Android screenshot notifications require Android 14; older Android versions still
37
- block capture with FLAG_SECURE. iOS secure-layer behavior requires device testing.
72
+ The application owns the warning UI, debouncing repeated events and when a
73
+ sensitive screen enters or leaves the protected state.
74
+
75
+ ## API
76
+
77
+ | Export | Signature | Platforms | Description |
78
+ | --- | --- | :-: | --- |
79
+ | `prevent()` | `() => Promise<void>` | iOS, Android | Enables screenshot, recording and app-switcher protection together. |
80
+ | `allow()` | `() => Promise<void>` | iOS, Android | Releases only the calling native object's protection. |
81
+ | `addListener(callback)` | `(event: CaptureEventType) => void` returns `{ remove(): void }` | iOS, Android | Subscribes to native events; `remove()` is idempotent. |
82
+ | `CaptureEventType` | `NONE`, `RECORDING`, `END_RECORDING`, `CAPTURED`, `APP_SWITCHING`, `UNKNOWN`, `ALLOW`, `PREVENT_SCREEN_CAPTURE`, `PREVENT_SCREEN_RECORDING`, `PREVENT_SCREEN_APP_SWITCHING` | iOS, Android | Event values forwarded from the native layer. |
83
+
84
+ At most 128 JavaScript subscribers per runtime and 32 native owner/subscriber
85
+ identities are admitted; excess registration throws. The native interface is in
86
+ [`src/ReactNativeCaptureProtection.nitro.ts`](src/ReactNativeCaptureProtection.nitro.ts).
87
+
88
+ ## Platform support
89
+
90
+ | Capability | iOS | Android | Web |
91
+ | --- | :-: | :-: | :-: |
92
+ | Screenshot protection | ✅ secure layer | ✅ `FLAG_SECURE` | — |
93
+ | Recording protection | ✅ | ✅ `FLAG_SECURE` | — |
94
+ | App-switcher protection | ✅ | ✅ | — |
95
+ | Screenshot event | ✅ notification | ✅ Android 14+ | — |
96
+ | Recording event | ✅ notification | ⚠️ virtual-display heuristic | — |
97
+ | Permission required | — | `DETECT_SCREEN_CAPTURE` (normal, 14+) | — |
98
+
99
+ ## Caveats
100
+
101
+ > [!WARNING]
102
+ > On iOS the protection uses an upstream-derived secure-text-field layer plus
103
+ > opaque windows; this is not a documented system-wide prevention API and needs
104
+ > device testing per OS version. Missing foreground activity/window or an
105
+ > unavailable secure layer rejects `prevent()`.
38
106
 
39
- See [SPEC](docs/SPEC.md) and [Acknowledgements](ACKNOWLEDGEMENTS.md).
107
+ > [!IMPORTANT]
108
+ > Protection is owned by the native object, not by a screen or a call. Repeated
109
+ > `prevent()` calls from one object are idempotent, and a separate runtime/object
110
+ > cannot release another object's protection. Coordinate prevent/allow when
111
+ > several sensitive screens share one JavaScript object.
40
112
 
41
- ## API and ownership
113
+ > [!NOTE]
114
+ > Android below 14 has no screenshot notification while blocking still works, and
115
+ > Android recording events are a virtual-display heuristic that may also reflect
116
+ > casting or external displays — they are not proof that a recording was made.
42
117
 
43
- | Method | Contract |
44
- | --- | --- |
45
- | `prevent()` | `Promise<void>`; request screenshot, recording and app-switcher protection together. |
46
- | `allow()` | `Promise<void>`; release only the calling native object's protection. |
47
- | `addListener(callback)` | Return a subscription with an idempotent `remove()` method. |
118
+ ## References
48
119
 
49
- Repeated `prevent()` calls by the same object are idempotent. Protection is owned
50
- by a native object rather than by each screen or each call: applications sharing
51
- one JS object across sensitive screens must coordinate their prevent/allow
52
- lifecycle. A separate runtime/object cannot release another object's protection.
120
+ - [Package spec](docs/SPEC.md)
121
+ - [Changelog](../../CHANGELOG.md)
53
122
 
54
- Remove subscriptions when their owner unmounts. Removing the final JS subscriber
55
- releases its native callback; it does not call `allow()`. There are at most 128
56
- JS subscribers per runtime and 32 native owner/subscriber identities. Excess
57
- registration throws. No providers, React hooks, custom-overlay API or upstream
58
- permission-request API is exported.
123
+ ## Upstream attribution
59
124
 
60
- ## Events and platform limits
125
+ <details>
126
+ <summary>Adapted from <code>react-native-capture-protection</code> 2.3.0</summary>
61
127
 
62
- `CaptureEventType` exports `NONE`, `RECORDING`, `END_RECORDING`, `CAPTURED`,
63
- `APP_SWITCHING`, `UNKNOWN`, `ALLOW`, `PREVENT_SCREEN_CAPTURE`,
64
- `PREVENT_SCREEN_RECORDING` and `PREVENT_SCREEN_APP_SWITCHING`. They represent
65
- native event values; the module never reads screenshot contents.
128
+ This module is adapted from
129
+ [react-native-capture-protection](https://github.com/wn-na/react-native-capture-protection)
130
+ version **2.3.0**, authored by **lethe / wn-na**. Thank you for the upstream
131
+ screenshot, recording and app-switcher protection implementation.
66
132
 
67
- Android declares `DETECT_SCREEN_CAPTURE`, a normal permission used for Android
68
- 14+ screenshot callbacks. Its recording events use a virtual-display heuristic,
69
- which can also reflect casting or external displays. It is not proof that a
70
- recording was made. iOS uses notifications, an upstream secure-text-field layer
71
- technique and opaque overlays; this is not a documented system-wide prevention
72
- API. Missing activity/window or an unavailable secure layer rejects protection.
133
+ The upstream code is distributed under the MIT license. Its copyright and full
134
+ license are retained in [`LICENSE.upstream`](LICENSE.upstream); the main
135
+ [`LICENSE`](LICENSE) also retains the upstream copyright for CocoaPods
136
+ acknowledgements. [`ACKNOWLEDGEMENTS.md`](ACKNOWLEDGEMENTS.md) identifies the
137
+ upstream subset and source provenance.
73
138
 
74
- Check nested navigation, recording, app-switcher snapshots, activity recreation
75
- and cleanup on each target device. The [contract](docs/SPEC.md) lists required
76
- runtime acceptance; source and unit checks do not establish physical capture
77
- prevention.
139
+ </details>
78
140
 
79
- ## License and attribution
141
+ ## License
80
142
 
81
- MIT; [LICENSE](LICENSE) covers this package and [LICENSE.upstream](LICENSE.upstream)
82
- preserves the adapted upstream notice. [ACKNOWLEDGEMENTS.md](ACKNOWLEDGEMENTS.md)
83
- identifies the upstream subset and source provenance.
143
+ MIT. See [LICENSE](LICENSE) for this package and
144
+ [LICENSE.upstream](LICENSE.upstream) for the adapted upstream notice.
@@ -1,3 +1,4 @@
1
1
  <manifest xmlns:android="http://schemas.android.com/apk/res/android">
2
- <uses-permission android:name="android.permission.DETECT_SCREEN_CAPTURE" android:minSdkVersion="34" />
2
+ <!-- The permission only exists on API 34+; older platforms ignore an unknown permission. -->
3
+ <uses-permission android:name="android.permission.DETECT_SCREEN_CAPTURE" />
3
4
  </manifest>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@onekeyfe/react-native-capture-protection",
3
- "version": "6.7.0-alpha.475",
3
+ "version": "6.8.0-3",
4
4
  "description": "Permission-minimal screenshot, recording and app-switcher protection",
5
5
  "main": "./lib/module/index.js",
6
6
  "types": "./lib/typescript/src/index.d.ts",
@@ -94,6 +94,7 @@
94
94
  "typescript": "^5.9.2"
95
95
  },
96
96
  "peerDependencies": {
97
+ "@onekeyfe/react-native-native-logger": "*",
97
98
  "react": "*",
98
99
  "react-native": "*",
99
100
  "react-native-nitro-modules": "0.37.0"