rn-secure-keystore
Version:
A comprehensive, cross-platform React Native wrapper for secure key-value storage using native security features of Android and iOS. It supports **biometric authentication**, **hardware-backed encryption**, and deep platform integrations such as **Android
188 lines • 7.33 kB
TypeScript
export interface HardwareSecurityInfo {
isHardwareBackedAvailable: boolean;
isStrongBoxAvailable: boolean;
recommendedSecurityLevel: 'strongbox' | 'hardware' | 'software';
}
export interface StorageOptions {
withBiometric?: boolean;
requireStrongBox?: boolean;
requireHardware?: boolean;
securityLevel?: 'auto' | 'strongbox' | 'hardware' | 'software';
allowFallback?: boolean;
accessGroup?: string | null;
accessControl?: string | null;
authenticatePrompt?: string;
authenticatePromptSubtitle?: string;
}
export interface GetItemOptions {
accessGroup?: string | null;
authenticatePrompt?: string;
authenticatePromptSubtitle?: string;
showModal?: boolean;
kLocalizedFallbackTitle?: string;
}
export declare class SecureStorageError extends Error {
code: string;
originalError?: Error | undefined;
constructor(message: string, code: string, originalError?: Error | undefined);
}
/**
* SecureStorage - React Native wrapper for secure key-value storage
*/
declare class SecureStorage {
/**
* Store a key-value pair securely
* @param key The key to store
* @param value The value to store
* @param options Storage options including security level
*/
static setItem(key: string, value: string, options?: StorageOptions): Promise<boolean>;
/**
* Retrieve a stored value by key
* @param key The key to retrieve
* @param options Retrieval options
*/
static getItem(key: string, options?: GetItemOptions): Promise<string | null>;
/**
* Remove a stored key-value pair
* @param key The key to remove
*/
static removeItem(key: string): Promise<boolean>;
/**
* Check if a key exists in storage
* @param key The key to check
*/
static hasItem(key: string): Promise<boolean>;
/**
* Get all stored keys
*/
static getAllKeys(): Promise<string[]>;
/**
* Clear all stored data
*/
static clear(): Promise<boolean>;
/**
* Check if biometric authentication is available
*/
static isBiometricAvailable(): Promise<boolean>;
/**
* Check if hardware-backed keystore is available
*/
static isHardwareBackedAvailable(): Promise<boolean>;
/**
* Check if StrongBox security is available (Android only)
* @returns Promise<boolean> - true if available on Android, false on iOS
*/
static isStrongBoxAvailable(): Promise<boolean>;
/**
* Get comprehensive hardware security information
* @returns Object containing all available security features and recommendations
*/
static getHardwareSecurityInfo(): Promise<HardwareSecurityInfo>;
/**
* Check if a specific key is stored with hardware-backed security
* @param key The key to check
* @returns True if the key is hardware-backed, false otherwise
*/
static isKeyHardwareBacked(key: string): Promise<boolean>;
/**
* Get security level for a specific key (Android only)
* @param key The key to check
* @returns Security level of the key
*/
static getKeySecurityLevel(key: string): Promise<string>;
/**
* Utility method to get security level recommendation for the current device
* @returns Recommended security level based on device capabilities
*/
static getRecommendedSecurityLevel(): Promise<'strongbox' | 'hardware' | 'software'>;
/**
* Utility method to check if a security level is available on the current device
* @param level The security level to check
* @returns True if the security level is available
*/
static isSecurityLevelAvailable(level: 'strongbox' | 'hardware'): Promise<boolean>;
/**
* Get security status for all stored keys
* @returns Object mapping keys to their security status
*/
static getSecurityStatus(): Promise<Record<string, {
exists: boolean;
isHardwareBacked: boolean;
securityLevel?: string;
}>>;
/**
* Android-specific: Set item with StrongBox security (if available)
* @param key The key to store
* @param value The value to store
* @param allowFallback Whether to allow fallback to hardware if StrongBox is not available
*/
static setStrongBoxItem(key: string, value: string, allowFallback?: boolean): Promise<boolean>;
/**
* iOS-specific: Set item with custom access control
* @param key The key to store
* @param value The value to store
* @param accessControl iOS access control level
* @param accessGroup iOS keychain access group
*/
static setKeychainItem(key: string, value: string, accessControl?: string, accessGroup?: string): Promise<boolean>;
/**
* Platform-specific capabilities check
* @returns Object with platform-specific feature availability
*/
static getPlatformCapabilities(): Promise<{
platform: string;
hasStrongBox: boolean;
hasHardwareBackedKeystore: boolean;
hasBiometrics: boolean;
hasKeychainAccessControl: boolean;
}>;
/**
* Utility method to migrate from plain storage to secure storage
* @param key The key to migrate
* @param plainValue The plain text value to secure
* @param options Security options for the new secure storage
*/
static migrateToSecureStorage(key: string, plainValue: string, options?: StorageOptions): Promise<boolean>;
/**
* Utility method to check if the current device meets minimum security requirements
* @param requirements Security requirements to check
*/
static meetsSecurityRequirements(requirements: {
requireBiometric?: boolean;
requireHardwareBacking?: boolean;
requireStrongBox?: boolean;
}): Promise<{
meets: boolean;
missing: string[];
}>;
}
export default SecureStorage;
export declare const ACCESS_CONTROL: {
readonly BIOMETRY_ANY: "kSecAccessControlBiometryAny";
readonly BIOMETRY_CURRENT_SET: "kSecAccessControlBiometryCurrentSet";
readonly DEVICE_PASSCODE: "kSecAccessControlDevicePasscode";
readonly APPLICATION_PASSWORD: "kSecAccessControlApplicationPassword";
readonly BIOMETRY_ANY_OR_DEVICE_PASSCODE: "kSecAccessControlBiometryAnyOrDevicePasscode";
};
export declare const ERROR_CODES: {
readonly AUTHENTICATION_CANCELLED: "AUTHENTICATION_CANCELLED";
readonly AUTHENTICATION_FAILED: "AUTHENTICATION_FAILED";
readonly BIOMETRIC_NOT_AVAILABLE: "BIOMETRIC_NOT_AVAILABLE";
readonly INTERACTION_NOT_ALLOWED: "INTERACTION_NOT_ALLOWED";
readonly PLATFORM_NOT_SUPPORTED: "PLATFORM_NOT_SUPPORTED";
readonly STRONGBOX_NOT_AVAILABLE: "STRONGBOX_NOT_AVAILABLE";
readonly INVALID_KEY: "INVALID_KEY";
readonly INVALID_VALUE: "INVALID_VALUE";
readonly STORAGE_ERROR: "STORAGE_ERROR";
readonly RETRIEVAL_ERROR: "RETRIEVAL_ERROR";
readonly REMOVAL_ERROR: "REMOVAL_ERROR";
readonly CLEAR_ERROR: "CLEAR_ERROR";
readonly GET_KEYS_ERROR: "GET_KEYS_ERROR";
readonly KEYCHAIN_ERROR: "KEYCHAIN_ERROR";
readonly CIPHER_ERROR: "CIPHER_ERROR";
readonly ACCESS_CONTROL_ERROR: "ACCESS_CONTROL_ERROR";
readonly SECURITY_INFO_ERROR: "SECURITY_INFO_ERROR";
readonly NO_ACTIVITY: "NO_ACTIVITY";
};
//# sourceMappingURL=index.d.ts.map