react-native-security-suite 0.9.22 → 1.0.0-rc.2

package/src/index.tsx

@@ -1,12 +1,89 @@
 import { NativeModules, Platform } from 'react-native';
-import AsyncStorage from '@react-native-async-storage/async-storage';
-import { isJsonString, jsonParse } from './helpers';
+import { jsonParse } from './helpers';
+import {
+  toNativeCryptoOptions,
+  type CryptoOptions,
+} from './legacy/cryptoOptions';
+import {
+  toNativeGenerateJWSOptions,
+  toNativeJwsFetchOptions,
+  type GenerateJWSOptions,
+  type JwsFetchOptions,
+} from './jws';
 
 export * from './SecureView';
+export type {
+  GenerateJWSOptions,
+  JwsAlgorithm,
+  JwsFetchOptions,
+  JwsHeaderValue,
+  JwsHeaders,
+  JwsPayload,
+} from './jws';
+
+export type {
+  CryptoOptions,
+  KeyAgreementAlgorithm,
+  KeyType,
+  EncryptionKeyAlgorithm,
+  HmacAlgorithm,
+  CipherAlgorithm,
+} from './legacy/cryptoOptions';
+
+export { SecurityError, SecurityErrorCode, mapNativeError, isSecurityError } from './errors';
+export { DeviceSecurity } from './device';
+export { RuntimeSecurity } from './runtime';
+export { AppIntegrity } from './integrity';
+export { Crypto } from './crypto';
+export { SecuritySuite } from './securitySuite';
+export type {
+  RuntimeThreatReport,
+  AppIntegrityReport,
+  DeviceEnvironment,
+  DeviceSecurityReport,
+  SecurityReport,
+  RiskLevel,
+  BuildType,
+} from './types/detection';
+
+/** @deprecated Use `JwsHeaders` (optional `Record<string, JwsHeaderValue>`) instead. */
+export interface LegacyJwsHeaders {
+  kid: string;
+  request_id: string;
+  [key: string]: string;
+}
+
+export interface SslPinningOptions {
+  /** Base64-encoded SPKI SHA-256 hashes (with or without `sha256/` prefix). */
+  certificates: string[];
+  /** Allowed hostnames. Request host must match one of these before pinning is evaluated. */
+  validDomains: string[];
+}
+
+interface Header {
+  [key: string]: string;
+}
+
+export interface Options {
+  body?: string | object;
+  headers: Header;
+  method?: 'DELETE' | 'GET' | 'POST' | 'PUT' | 'PATCH';
+  timeout?: number;
+  /** SSL pinning configuration. Both certificates and validDomains are required together. */
+  certificates?: string[];
+  validDomains?: string[];
+  /** @deprecated Use `jws` instead. */
+  keyId?: string;
+  /** @deprecated Use `jws` instead. */
+  requestId?: string;
+  /**
+   * @deprecated Legacy signing secret. Use `jws.secret` instead.
+   */
+  secret?: string;
+  /** JWS request-signing configuration. */
+  jws?: JwsFetchOptions;
+}
 
-/*
- * SSL Pinnning start
- */
 interface Response {
   status: number;
   url: string;
@@ -26,19 +103,6 @@ export interface ErrorResponse extends Response {
   code: string;
 }
 
-interface Header {
-  [key: string]: string;
-}
-
-export interface Options {
-  body?: string | object;
-  headers: Header;
-  method?: 'DELETE' | 'GET' | 'POST' | 'PUT';
-  certificates?: string[];
-  validDomains?: string[];
-  timeout?: number;
-}
-
 export interface FetchEventResponse {
   url: string;
   options: Options;
@@ -61,7 +125,7 @@ const LINKING_ERROR =
   '- You rebuilt the app after installing the package\n' +
   '- You are not using Expo managed workflow\n';
 
-const SecuritySuite = NativeModules.SecuritySuite
+const NativeSecuritySuiteModule = NativeModules.SecuritySuite
   ? NativeModules.SecuritySuite
   : new Proxy(
       {},
@@ -72,234 +136,268 @@ const SecuritySuite = NativeModules.SecuritySuite
       }
     );
 
-export const getPublicKey = (): Promise<string> => SecuritySuite.getPublicKey();
+export const getPublicKey = (): Promise<string> =>
+  NativeSecuritySuiteModule.getPublicKey();
+
+/**
+ * @deprecated Prefer `Crypto.establishSharedKey()` which keeps the derived key in native memory.
+ */
+export const getSharedKey = (
+  serverPublicKey: string,
+  options?: CryptoOptions
+): Promise<string> =>
+  NativeSecuritySuiteModule.getSharedKey(serverPublicKey, toNativeCryptoOptions(options));
+
+export const encryptBySharedKey = (
+  input: string,
+  options?: CryptoOptions
+): Promise<string> => {
+  if (!input || typeof input !== 'string') {
+    return Promise.reject(new Error('Input must be a non-empty string'));
+  }
+  return NativeSecuritySuiteModule.encrypt(input, toNativeCryptoOptions(options));
+};
+
+export const decryptBySharedKey = (
+  input: string,
+  options?: CryptoOptions
+): Promise<string> => {
+  if (!input || typeof input !== 'string') {
+    return Promise.reject(new Error('Input must be a non-empty string'));
+  }
+  return NativeSecuritySuiteModule.decrypt(input, toNativeCryptoOptions(options));
+};
+
+export const generateJWS = (options: GenerateJWSOptions): Promise<string> => {
+  const nativeOptions = toNativeGenerateJWSOptions(options);
+  return NativeSecuritySuiteModule.generateJWS(nativeOptions);
+};
 
-export const getSharedKey = (serverPublicKey: string): Promise<string> =>
-  SecuritySuite.getSharedKey(serverPublicKey);
+function normalizeFetchOptions(options: Options): Options {
+  if (!options.jws) {
+    return options;
+  }
 
-export const encryptBySharedKey = (input: string): Promise<string> =>
-  input && typeof input === 'string' ? SecuritySuite.encrypt(input) : '';
+  const nativeJws = toNativeJwsFetchOptions(options.jws);
+  return {
+    ...options,
+    jws: {
+      algorithm: nativeJws.algorithm,
+      secret: nativeJws.secret,
+      headers: nativeJws.headers,
+      detached: nativeJws.detached,
+      ...(options.jws.headerName ? { headerName: options.jws.headerName } : {}),
+      ...(options.jws.payload !== undefined
+        ? { payload: nativeJws.payload }
+        : {}),
+    },
+  };
+}
 
-export const decryptBySharedKey = (input: string) =>
-  input && typeof input === 'string' ? SecuritySuite.decrypt(input) : '';
+/**
+ * Local obfuscation only — NOT secure encryption. Requires an explicit secret.
+ * Never use for credentials, tokens, or PII at rest.
+ */
+export const obfuscate = (input: string, secret: string): Promise<string> =>
+  NativeSecuritySuiteModule.obfuscate(input, secret);
+
+export const deobfuscate = (input: string, secret: string): Promise<string> =>
+  NativeSecuritySuiteModule.deobfuscate(input, secret);
 
 export const getDeviceId = (): Promise<string> =>
-  new Promise((resolve: any, reject: any) => {
-    SecuritySuite.getDeviceId((result: string | null, error: string | null) => {
+  new Promise((resolve, reject) => {
+    NativeSecuritySuiteModule.getDeviceId((result: string | null, error: string | null) => {
       if (error !== null) reject(error);
-      else resolve(result);
+      else if (result !== null) resolve(result);
+      else reject(new Error('GET_DEVICE_ID_ERROR'));
     });
   });
 
+/**
+ * @deprecated Use `obfuscate()` with an explicit secret, or `SecureStorage` for at-rest data.
+ */
 export const encrypt = (
   input: string,
   hardEncryption = true,
-  secretKey = null
+  secretKey: string | null = null
 ): Promise<string> =>
-  new Promise((resolve: any, reject: any) => {
-    if (!input) resolve(input);
-
-    SecuritySuite.storageEncrypt(
+  new Promise((resolve, reject) => {
+    if (!input) {
+      resolve(input);
+      return;
+    }
+    if (!secretKey) {
+      reject(
+        new Error(
+          'secretKey is required. Device identifiers are not accepted as encryption keys.'
+        )
+      );
+      return;
+    }
+    NativeSecuritySuiteModule.storageEncrypt(
       input,
       secretKey,
       hardEncryption,
       (result: string | null, error: string | null) => {
         if (error !== null) reject(error);
-        else resolve(result);
+        else if (result !== null) resolve(result);
+        else reject(new Error('ENCRYPT_ERROR'));
       }
     );
   });
 
+/**
+ * @deprecated Use `deobfuscate()` with an explicit secret, or `SecureStorage` for at-rest data.
+ */
 export const decrypt = (
   input: string,
   hardEncryption = true,
-  secretKey = null
+  secretKey: string | null = null
 ): Promise<string> =>
-  new Promise((resolve: any, reject: any) => {
-    if (!input) resolve(input);
-
-    SecuritySuite.storageDecrypt(
+  new Promise((resolve, reject) => {
+    if (!input) {
+      resolve(input);
+      return;
+    }
+    if (!secretKey) {
+      reject(
+        new Error(
+          'secretKey is required. Device identifiers are not accepted as encryption keys.'
+        )
+      );
+      return;
+    }
+    NativeSecuritySuiteModule.storageDecrypt(
       input,
       secretKey,
       hardEncryption,
       (result: string | null, error: string | null) => {
         if (error !== null) reject(error);
-        else resolve(result);
+        else if (result !== null) resolve(result);
+        else reject(new Error('DECRYPT_ERROR'));
       }
     );
   });
 
+const SECURE_STORAGE_FAILED = 'Secure storage operation failed';
+
+function wrapSecureStorage<T>(operation: string, promise: Promise<T>): Promise<T> {
+  return promise.catch((error: unknown) => {
+    const detail =
+      error instanceof Error
+        ? error.message
+        : typeof error === 'string'
+          ? error
+          : 'Unknown error';
+    throw new Error(`${SECURE_STORAGE_FAILED} (${operation}): ${detail}`);
+  });
+}
+
+/** Hardware-backed encrypted storage (Keychain on iOS, EncryptedSharedPreferences on Android). */
 export const SecureStorage = {
-  setItem: async (key: string, value: string): Promise<void> => {
-    try {
-      const encryptedKey = await encrypt(key, false);
-      const encryptedValue = await encrypt(value);
-      return AsyncStorage.setItem(encryptedKey, encryptedValue);
-    } catch (e) {
-      console.error('setItem error: ', e);
-    }
-  },
-  getItem: async (key: string): Promise<string | null> => {
-    try {
-      const encryptedKey = await encrypt(key, false);
-      const encryptedData = await AsyncStorage.getItem(encryptedKey);
-      return decrypt(encryptedData ?? '');
-    } catch (e) {
-      console.error('getItem error: ', e);
-      return '';
-    }
-  },
-  mergeItem: async (key: string, value: string): Promise<void> => {
-    try {
-      const encryptedKey = await encrypt(key, false);
-      const encryptedData = await AsyncStorage.getItem(encryptedKey);
-      const data = await decrypt(encryptedData ?? '');
-      if (!isJsonString(data) || !isJsonString(value)) return;
-      const mergedData = await JSON.stringify(
-        Object.assign(JSON.parse(data), JSON.parse(value))
-      );
-      const encryptedValue = await encrypt(mergedData);
-      return AsyncStorage.setItem(encryptedKey, encryptedValue);
-    } catch (e) {
-      console.error('mergeItem error: ', e);
-    }
-  },
-  removeItem: async (key: string): Promise<void> => {
-    try {
-      const encryptedKey = await encrypt(key, false);
-      return AsyncStorage.removeItem(encryptedKey);
-    } catch (e) {
-      console.error('removeItem error: ', e);
-    }
-  },
-  getAllKeys: async (): Promise<readonly string[]> => {
-    try {
-      const encryptedKeys = await AsyncStorage.getAllKeys();
-      return await Promise.all(
-        encryptedKeys.map(async (item: string): Promise<string> => {
-          const decryptedKey = await decrypt(item, false);
-          return decryptedKey ? decryptedKey : item;
-        })
-      );
-    } catch (e) {
-      console.error('getAllKeys error: ', e);
-      return [];
-    }
-  },
-  multiSet: async (keyValuePairs: Array<Array<string>>): Promise<void> => {
-    try {
-      const encryptedKeyValuePairs: any = await Promise.all(
-        keyValuePairs.map(async (item: Array<string>) => {
-          if (item.length === 2 && item[0] && item[1]) {
-            const encryptedKey = await encrypt(item[0], false);
-            const encryptedValue = await encrypt(item[1]);
-            return [encryptedKey, encryptedValue];
-          }
-
-          return null;
-        })
-      );
-      AsyncStorage.multiSet(encryptedKeyValuePairs);
-    } catch (e) {
-      console.error('multiSet error: ', e);
-    }
+  setItem: (key: string, value: string): Promise<void> =>
+    wrapSecureStorage(
+      'setItem',
+      NativeSecuritySuiteModule.secureStorageSetItem(key, value)
+    ),
+
+  getItem: (key: string): Promise<string | null> =>
+    wrapSecureStorage(
+      'getItem',
+      NativeSecuritySuiteModule.secureStorageGetItem(key)
+    ),
+
+  removeItem: (key: string): Promise<void> =>
+    wrapSecureStorage(
+      'removeItem',
+      NativeSecuritySuiteModule.secureStorageRemoveItem(key)
+    ),
+
+  getAllKeys: (): Promise<string[]> =>
+    wrapSecureStorage(
+      'getAllKeys',
+      NativeSecuritySuiteModule.secureStorageGetAllKeys()
+    ),
+
+  clear: (): Promise<void> =>
+    wrapSecureStorage('clear', NativeSecuritySuiteModule.secureStorageClear()),
+
+  multiSet: async (keyValuePairs: Array<[string, string]>): Promise<void> => {
+    await Promise.all(
+      keyValuePairs.map(([key, value]) => SecureStorage.setItem(key, value))
+    );
   },
+
   multiGet: async (
-    keys: Array<string>
-  ): Promise<readonly [string, string | null][]> => {
-    try {
-      if (!Array.isArray(keys)) return [];
-      const encryptedKeys = await Promise.all(
-        keys.map(
-          async (item: string): Promise<string> => await encrypt(item, false)
-        )
-      );
-      const encryptedItems = await AsyncStorage.multiGet(encryptedKeys);
-      return await Promise.all(
-        encryptedItems && encryptedItems.length
-          ? encryptedItems.map(async (item: any): Promise<[string, string]> => {
-              const decryptedKey = await decrypt(item[0], false);
-              const decryptedalue = await decrypt(item[1]);
-              return [decryptedKey, decryptedalue];
-            })
-          : []
-      );
-    } catch (e) {
-      console.error('multiGet error: ', e);
-      return [];
-    }
+    keys: string[]
+  ): Promise<readonly [string, string | null][]> =>
+    Promise.all(
+      keys.map(async (key): Promise<[string, string | null]> => [
+        key,
+        await SecureStorage.getItem(key),
+      ])
+    ),
+
+  multiRemove: async (keys: string[]): Promise<void> => {
+    await Promise.all(keys.map((key) => SecureStorage.removeItem(key)));
   },
-  multiMerge: async (keyValuePairs: Array<Array<string>>): Promise<void> => {
-    try {
-      keyValuePairs.map(async (item: Array<string>) => {
-        if (item.length === 2 && item[0] && item[1]) {
-          const encryptedKey = await encrypt(item[0], false);
-          const encryptedData = await AsyncStorage.getItem(item[0]);
-          const data = await decrypt(encryptedData ?? '');
-          if (!isJsonString(data) || !isJsonString(item[1])) return null;
-          const mergedData = await JSON.stringify(
-            Object.assign(JSON.parse(data), JSON.parse(item[1]))
-          );
-          const encryptedValue = await encrypt(mergedData, false);
-          return AsyncStorage.setItem(encryptedKey, encryptedValue);
-        }
 
-        return null;
-      });
-    } catch (e) {
-      console.error('multiMerge error: ', e);
+  /** @deprecated Use multiSet instead. */
+  mergeItem: async (key: string, value: string): Promise<void> => {
+    const existing = await SecureStorage.getItem(key);
+    if (!existing) {
+      await SecureStorage.setItem(key, value);
+      return;
     }
-  },
-  multiRemove: async (keys: Array<string>): Promise<void> => {
     try {
-      if (!Array.isArray(keys)) return keys;
-      const encryptedKeys = await Promise.all(
-        keys.map(
-          async (item: string): Promise<string> => await encrypt(item, false)
-        )
-      );
-      return AsyncStorage.multiRemove(encryptedKeys);
-    } catch (e) {
-      console.error('multiRemove error: ', e);
+      const merged = JSON.stringify({
+        ...JSON.parse(existing),
+        ...JSON.parse(value),
+      });
+      await SecureStorage.setItem(key, merged);
+    } catch {
+      throw new Error('mergeItem requires valid JSON strings');
     }
   },
-  clear: async (): Promise<void> => {
-    try {
-      return AsyncStorage.clear();
-    } catch (e) {
-      console.error('clear error: ', e);
-    }
+
+  /** @deprecated Use multiSet instead. */
+  multiMerge: async (keyValuePairs: Array<[string, string]>): Promise<void> => {
+    await Promise.all(
+      keyValuePairs.map(([key, value]) => SecureStorage.mergeItem(key, value))
+    );
   },
 };
 
 export function fetch(
   url: string,
   options: Options,
-  loggerIsEnabled = false
+  loggerIsEnabled = __DEV__
 ): Promise<SuccessResponse | ErrorResponse> {
   return new Promise((resolve, reject) => {
-    SecuritySuite.fetch(
+    NativeSecuritySuiteModule.fetch(
       url,
-      { ...options, loggerIsEnabled },
+      { ...normalizeFetchOptions(options), loggerIsEnabled },
       (result: SuccessResponse, error: ErrorResponse) => {
-        try {
-          if (error === null) {
-            resolve({
-              ...result,
-              json: () => jsonParse(result.response),
-            });
-          } else {
-            const errorJson = jsonParse(error.error);
-            reject({
-              json: () => errorJson,
-              error: error?.error ?? error,
-              status: error?.status ?? '',
-              url: error?.url ?? '',
-              ...errorJson,
-            });
-          }
-        } catch (e) {
-          console.error('SSL Pinnning fetch error: ', e);
+        if (error === null) {
+          resolve({
+            ...result,
+            json: () => jsonParse(result.response),
+          });
+        } else {
+          const errorJson = jsonParse(
+            typeof error?.error === 'string' ? error.error : JSON.stringify(error)
+          );
+          reject({
+            json: () => errorJson,
+            error: error?.error ?? error,
+            status: error?.status ?? 0,
+            url: error?.url ?? url,
+            path: errorJson?.path ?? '',
+            message: errorJson?.message ?? String(error?.error ?? error),
+            code: errorJson?.code ?? '',
+            duration: error?.duration ?? '',
+            ...errorJson,
+          });
         }
       }
     );
@@ -307,7 +405,7 @@ export function fetch(
 }
 
 export function deviceHasSecurityRisk(): Promise<boolean> {
-  return SecuritySuite.deviceHasSecurityRisk();
+  return NativeSecuritySuiteModule.deviceHasSecurityRisk();
 }
 
-export default SecuritySuite;
+export default NativeSecuritySuiteModule;

package/src/integrity/index.ts

@@ -0,0 +1,46 @@
+import { getNativeModule } from '../native/bridge';
+import type { AppIntegrityReport, BuildType } from '../types/detection';
+
+function parseBuildType(value: unknown): BuildType {
+  if (value === 'debug' || value === 'release' || value === 'testflight') {
+    return value;
+  }
+  return 'release';
+}
+
+function parseIntegrityReport(raw: Record<string, unknown>): AppIntegrityReport {
+  const report: AppIntegrityReport = {
+    validSignature: Boolean(raw.validSignature),
+    debuggable: Boolean(raw.debuggable),
+    tampered: Boolean(raw.tampered),
+    buildType: parseBuildType(raw.buildType),
+  };
+
+  if (raw.installerTrusted !== undefined) {
+    report.installerTrusted = Boolean(raw.installerTrusted);
+  }
+
+  if (typeof raw.signingCertificateSha256 === 'string') {
+    report.signingCertificateSha256 = raw.signingCertificateSha256;
+  }
+
+  if (raw.installerPackage === null || typeof raw.installerPackage === 'string') {
+    report.installerPackage = raw.installerPackage as string | null;
+  }
+
+  if (typeof raw.bundleIdentifier === 'string') {
+    report.bundleIdentifier = raw.bundleIdentifier;
+  }
+
+  return report;
+}
+
+export const AppIntegrity = {
+  verify(): Promise<AppIntegrityReport> {
+    return getNativeModule()
+      .appIntegrityVerify()
+      .then((result) => parseIntegrityReport(result));
+  },
+};
+
+export type { AppIntegrityReport, BuildType };