Skip to content

Commit fa3757c

Browse files
tompsotaclaude
andauthored
feat!: unify the public API with the other freeRASP plugins (#172)
* feat!: unify the public API with the other freeRASP plugins - TalsecIosConfig.appBundleId (string) -> appBundleIds (string[]), as in the iOS SDK - methods that resolved with status strings or constants resolve to void - all methods reject with TalsecError carrying a stable code, including Android-only methods called on iOS - onInvalidCallback and removeListenerForEvent are no longer exported; abortApp is the only exported internal helper Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * feat: return start status and errors from useFreeRasp useFreeRasp returns { started, error } instead of only logging failures, so apps can react when the listeners can't be registered or freeRASP fails to start. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor(types): type threat and execution state actions as returning void Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 8023a65 commit fa3757c

15 files changed

Lines changed: 262 additions & 99 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,11 +13,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
1313
### Breaking
1414

1515
- `allChecksFinished` RASP execution state action renamed to `fastChecksFinished`. On Android, it is triggered when the fast checks are completed, while the postponed checks may still run; on iOS, when all checks are completed
16+
- `TalsecIosConfig.appBundleId` (string) replaced by `appBundleIds` (string[]), matching the iOS SDK
17+
- Methods that resolved with a status string or a constant now resolve to `void`: `talsecStart`, `addToWhitelist`, `blockScreenCapture`, `blockScreenControl`, `startOngoingCallDetection`, `stopOngoingCallDetection`, `storeExternalId`, `removeExternalId`
18+
- All methods now reject with `TalsecError` (`code`: `talsec-failure`, `unsupported-platform`, `configuration-exception`, `external-id-failure`, `malware-failure`) instead of native errors or plain strings
19+
- `onInvalidCallback` and `removeListenerForEvent` are no longer exported; use `abortApp` to terminate the app
1620

1721
### React Native
1822

1923
#### Added
2024

25+
- `useFreeRasp` returns `{ started, error }`; `error` is the `TalsecError` that prevented the listeners from being registered or freeRASP from starting, which was previously only logged to the console
2126
- `ongoingCall` threat action with the new `CallState` type (`'STARTED' | 'ONGOING' | 'STOPPED'`), driven by `startOngoingCallDetection()` and `stopOngoingCallDetection()` (Android only)
2227
- `blockScreenControl()` and `isScreenControlBlocked()` to prevent accessibility services from reading or controlling the app screen (Android only)
2328
- `blockOverlayWindows()` and `isOverlayWindowsBlocked()` to hide overlay windows of other apps (Android 12+ only, requires the `HIDE_OVERLAY_WINDOWS` permission)
@@ -27,6 +32,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
2732

2833
- Android package (namespace) of the plugin renamed from `com.freeraspreactnative` to `app.talsec.rasp.reactnative`, following the Android SDK's `app.talsec.rasp` (update the import if you register `FreeraspReactNativePackage` manually)
2934
- On Android, `isScreenCaptureBlocked()` reports the protection state of the current activity
35+
- Threat and RASP execution state actions are typed as returning `void` instead of `any`
3036

3137
### Android
3238

‎example/src/App.tsx‎

Lines changed: 16 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ const App = () => {
6767
},
6868
},
6969
iosConfig: {
70-
appBundleId: 'org.reactjs.native.example.FreeraspReactNativeExample',
70+
appBundleIds: ['org.reactjs.native.example.FreeraspReactNativeExample'],
7171
appTeamId: 'your_team_ID',
7272
},
7373
watcherMail: 'your_email_address@example.com',
@@ -351,18 +351,28 @@ const App = () => {
351351
await Promise.all(
352352
appsToWhitelist.map(async (app) => {
353353
try {
354-
const whitelistResponse = await addToWhitelist(app);
355-
console.info(
356-
`${app} stored to Malware Whitelist: ${whitelistResponse}`
357-
);
354+
await addToWhitelist(app);
355+
console.info(`${app} stored to Malware Whitelist`);
358356
} catch (error) {
359357
console.info('Malware whitelist failed: ', error);
360358
}
361359
})
362360
);
363361
};
364362

365-
useFreeRasp(config, actions, raspExecutionStateActions);
363+
const { error: raspError } = useFreeRasp(
364+
config,
365+
actions,
366+
raspExecutionStateActions
367+
);
368+
369+
useEffect(() => {
370+
if (raspError) {
371+
console.error(
372+
`freeRASP failed to start: ${raspError.code}: ${raspError.message}`
373+
);
374+
}
375+
}, [raspError]);
366376

367377
return (
368378
<DemoApp

‎example/src/DemoApp.tsx‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -75,8 +75,7 @@ export const DemoApp: React.FC<{
7575

7676
const toggleScreenCaptureBlock = async () => {
7777
try {
78-
const response = await blockScreenCapture(!hasScreenCaptureBlocked);
79-
console.info('Changing Screen Capture Status:', response);
78+
await blockScreenCapture(!hasScreenCaptureBlocked);
8079
await updateScreenCaptureStatus();
8180
} catch (error: any) {
8281
console.error('Screen capture Error:', error.message);

‎example/src/MalwareItem.tsx‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -28,10 +28,8 @@ export const MalwareItem: React.FC<{ app: SuspiciousAppInfo }> = ({ app }) => {
2828

2929
const whitelistApp = async (packageName: string) => {
3030
try {
31-
const whitelistResponse = await addToWhitelist(packageName);
32-
console.info(
33-
`Malware Whitelist response for ${app}: ${whitelistResponse}`
34-
);
31+
await addToWhitelist(packageName);
32+
console.info(`${app.packageInfo.packageName} added to Malware Whitelist`);
3533
alert('Restart app for whitelist to take effect');
3634
} catch (error: any) {
3735
console.info('Error while adding app to malware whitelist: ', error);

‎ios/FreeraspReactNative.swift‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -51,8 +51,8 @@ class FreeraspReactNative: RCTEventEmitter {
5151
guard let iosConfig = talsecConfig["iosConfig"] as? NSDictionary else {
5252
throw NSError(domain: "Missing iosConfig parameter in Talsec Native Plugin", code: 1)
5353
}
54-
guard let appBundleIds = iosConfig["appBundleId"] as? String else {
55-
throw NSError(domain: "Missing appBundleId parameter in Talsec Native Plugin", code: 2)
54+
guard let appBundleIds = iosConfig["appBundleIds"] as? [String] else {
55+
throw NSError(domain: "Missing appBundleIds parameter in Talsec Native Plugin", code: 2)
5656
}
5757
guard let appTeamId = iosConfig["appTeamId"] as? String else {
5858
throw NSError(domain: "Missing appTeamId parameter in Talsec Native Plugin", code: 3)
@@ -62,7 +62,7 @@ class FreeraspReactNative: RCTEventEmitter {
6262
}
6363
let isProd = talsecConfig["isProd"] as? Bool ?? true
6464

65-
let config = TalsecConfig(appBundleIds: [appBundleIds], appTeamId: appTeamId, watcherMailAddress: watcherMailAddress, isProd: isProd)
65+
let config = TalsecConfig(appBundleIds: appBundleIds, appTeamId: appTeamId, watcherMailAddress: watcherMailAddress, isProd: isProd)
6666
Talsec.start(config: config)
6767
}
6868

‎src/api/listeners/raspExecutionState.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
import { NativeEventEmitter, type EmitterSubscription } from 'react-native';
22
import { FreeraspReactNative } from '../nativeModules';
3-
import { onInvalidCallback, removeListenerForEvent } from '../methods/native';
3+
import { onInvalidCallback, removeListenerForEvent } from '../methods/internal';
44
import type {
55
NativeEvent,
66
RaspExecutionStateEventActions,

‎src/api/listeners/threat.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
import { NativeEventEmitter, type EmitterSubscription } from 'react-native';
22
import { FreeraspReactNative } from '../nativeModules';
3-
import { onInvalidCallback, removeListenerForEvent } from '../methods/native';
3+
import { onInvalidCallback, removeListenerForEvent } from '../methods/internal';
44
import { Threat } from '../../models/threat';
55
import type {
66
CallState,

‎src/api/methods/internal.ts‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
import { FreeraspReactNative } from '../nativeModules';
2+
3+
/**
4+
* Terminates the app. Called when the native side sends data that freeRASP
5+
* never sends, which indicates tampering. Exported publicly as `abortApp`.
6+
*/
7+
export const onInvalidCallback = (): void => {
8+
FreeraspReactNative.onInvalidCallback();
9+
};
10+
11+
export const removeListenerForEvent = (channel: string): Promise<string> => {
12+
return FreeraspReactNative.removeListenerForEvent(channel);
13+
};

‎src/api/methods/native.ts‎

Lines changed: 72 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,60 @@
11
import { Platform } from 'react-native';
22
import { FreeraspReactNative } from '../nativeModules';
33
import type { TalsecConfig } from '../../types/types';
4+
import { androidOnly, wrapNative } from '../../types/errors';
45
import { withDefaults } from '../../utils/config';
56

6-
export const talsecStart = async (options: TalsecConfig): Promise<string> => {
7-
return FreeraspReactNative.talsecStart(withDefaults(options));
7+
/**
8+
* Starts freeRASP. Prefer the `useFreeRasp` hook, which also registers the
9+
* listeners.
10+
*/
11+
export const talsecStart = async (options: TalsecConfig): Promise<void> => {
12+
await wrapNative('talsec-failure', () =>
13+
FreeraspReactNative.talsecStart(withDefaults(options))
14+
);
815
};
916

10-
export const addToWhitelist = async (packageName: string): Promise<boolean> => {
17+
/**
18+
* Android only. Adds an app to the malware whitelist so it is not reported.
19+
*/
20+
export const addToWhitelist = async (packageName: string): Promise<void> => {
1121
if (Platform.OS === 'ios') {
12-
return Promise.reject('Malware detection not available on iOS');
22+
return androidOnly('Malware detection');
1323
}
14-
return FreeraspReactNative.addToWhitelist(packageName);
24+
await wrapNative('malware-failure', () =>
25+
FreeraspReactNative.addToWhitelist(packageName)
26+
);
1527
};
1628

17-
export const blockScreenCapture = (enable: boolean): Promise<string> => {
18-
return FreeraspReactNative.blockScreenCapture(enable);
29+
/**
30+
* Blocks or unblocks screenshots and screen recording of the app screen.
31+
*/
32+
export const blockScreenCapture = async (enable: boolean): Promise<void> => {
33+
await wrapNative('talsec-failure', () =>
34+
FreeraspReactNative.blockScreenCapture(enable)
35+
);
1936
};
2037

38+
/**
39+
* Returns whether screen capture is blocked for the current screen.
40+
*/
2141
export const isScreenCaptureBlocked = (): Promise<boolean> => {
22-
return FreeraspReactNative.isScreenCaptureBlocked();
42+
return wrapNative('talsec-failure', () =>
43+
FreeraspReactNative.isScreenCaptureBlocked()
44+
);
2345
};
2446

25-
const androidOnly = (feature: string): Promise<never> =>
26-
Promise.reject(`${feature} not available on iOS`);
27-
2847
/**
2948
* Android only. Prevents accessibility services from reading or controlling
3049
* the app screen.
3150
*/
32-
export const blockScreenControl = (enable: boolean): Promise<string> => {
51+
export const blockScreenControl = async (enable: boolean): Promise<void> => {
3352
if (Platform.OS === 'ios') {
3453
return androidOnly('Screen control blocking');
3554
}
36-
return FreeraspReactNative.blockScreenControl(enable);
55+
await wrapNative('talsec-failure', () =>
56+
FreeraspReactNative.blockScreenControl(enable)
57+
);
3758
};
3859

3960
/**
@@ -43,7 +64,9 @@ export const isScreenControlBlocked = (): Promise<boolean> => {
4364
if (Platform.OS === 'ios') {
4465
return androidOnly('Screen control blocking');
4566
}
46-
return FreeraspReactNative.isScreenControlBlocked();
67+
return wrapNative('talsec-failure', () =>
68+
FreeraspReactNative.isScreenControlBlocked()
69+
);
4770
};
4871

4972
/**
@@ -56,7 +79,9 @@ export const blockOverlayWindows = (enable: boolean): Promise<boolean> => {
5679
if (Platform.OS === 'ios') {
5780
return androidOnly('Overlay windows blocking');
5881
}
59-
return FreeraspReactNative.blockOverlayWindows(enable);
82+
return wrapNative('talsec-failure', () =>
83+
FreeraspReactNative.blockOverlayWindows(enable)
84+
);
6085
};
6186

6287
/**
@@ -66,51 +91,62 @@ export const isOverlayWindowsBlocked = (): Promise<boolean> => {
6691
if (Platform.OS === 'ios') {
6792
return androidOnly('Overlay windows blocking');
6893
}
69-
return FreeraspReactNative.isOverlayWindowsBlocked();
94+
return wrapNative('talsec-failure', () =>
95+
FreeraspReactNative.isOverlayWindowsBlocked()
96+
);
7097
};
7198

7299
/**
73100
* Android only. Starts the ongoing call (cellular and VoIP) detection.
74101
* Call states are reported through the `ongoingCall` threat action.
75102
*/
76-
export const startOngoingCallDetection = (): Promise<string> => {
103+
export const startOngoingCallDetection = async (): Promise<void> => {
77104
if (Platform.OS === 'ios') {
78105
return androidOnly('Ongoing call detection');
79106
}
80-
return FreeraspReactNative.startOngoingCallDetection();
107+
await wrapNative('talsec-failure', () =>
108+
FreeraspReactNative.startOngoingCallDetection()
109+
);
81110
};
82111

83112
/**
84113
* Android only. Stops the ongoing call detection.
85114
*/
86-
export const stopOngoingCallDetection = (): Promise<string> => {
115+
export const stopOngoingCallDetection = async (): Promise<void> => {
87116
if (Platform.OS === 'ios') {
88117
return androidOnly('Ongoing call detection');
89118
}
90-
return FreeraspReactNative.stopOngoingCallDetection();
119+
await wrapNative('talsec-failure', () =>
120+
FreeraspReactNative.stopOngoingCallDetection()
121+
);
91122
};
92123

93-
export const storeExternalId = (data: string): Promise<string> => {
94-
return FreeraspReactNative.storeExternalId(data);
124+
/**
125+
* Stores an external ID sent with freeRASP logs.
126+
*/
127+
export const storeExternalId = async (data: string): Promise<void> => {
128+
await wrapNative('external-id-failure', () =>
129+
FreeraspReactNative.storeExternalId(data)
130+
);
95131
};
96132

97-
export const removeExternalId = (): Promise<string> => {
98-
return FreeraspReactNative.removeExternalId();
133+
/**
134+
* Removes the stored external ID.
135+
*/
136+
export const removeExternalId = async (): Promise<void> => {
137+
await wrapNative('external-id-failure', () =>
138+
FreeraspReactNative.removeExternalId()
139+
);
99140
};
100141

142+
/**
143+
* Android only. Returns the icon of the given app as a base64-encoded PNG.
144+
*/
101145
export const getAppIcon = (packageName: string): Promise<string> => {
102146
if (Platform.OS === 'ios') {
103-
return Promise.reject(
104-
'App icon retrieval for Malware detection not available on iOS'
105-
);
147+
return androidOnly('App icon retrieval for malware detection');
106148
}
107-
return FreeraspReactNative.getAppIcon(packageName);
108-
};
109-
110-
export const onInvalidCallback = (): void => {
111-
FreeraspReactNative.onInvalidCallback();
112-
};
113-
114-
export const removeListenerForEvent = (channel: string): Promise<string> => {
115-
return FreeraspReactNative.removeListenerForEvent(channel);
149+
return wrapNative('malware-failure', () =>
150+
FreeraspReactNative.getAppIcon(packageName)
151+
);
116152
};

0 commit comments

Comments
 (0)