capacitor-secure-credentials-plugin

Saves credentials using secure native technology (Keychain on iOS and Android), with configurable protection levels from simply encrypted, device unlocked, user presence, to user presence proved with biometrics.

Install

npm install capacitor-secure-credentials-plugin
npx cap sync

API

• getCredential(...)
• getUsernames(...)
• removeCredential(...)
• removeCredentials(...)
• setCredential(...)
• availableSecurityStrategies()
• supportedBiometricSensors()
• Interfaces
• Type Aliases
• Enums

getCredential(...)

getCredential(options: { service: string; username: string; }) => Promise<Success<Credential> | Failure<SecureCredentialsError>>

Get a credential matching a service and username if one exists. The user may be challenged to authenticate this request every time it is called.

| Param | Type | | ------------- | --------------------------------------------------- | | options | { service: string; username: string; } |

Returns: Promise<Success<Credential> | Failure<SecureCredentialsError>>

getUsernames(...)

getUsernames(options: { service: string; }) => Promise<Success<string[]> | Failure<SecureCredentialsError>>

Get all usernames that have credentials stored for a service.

| Param | Type | | ------------- | --------------------------------- | | options | { service: string; } |

Returns: Promise<Failure<SecureCredentialsError> | Success<string[]>>

removeCredential(...)

removeCredential(options: { service: string; username: string; }) => Promise<Success<boolean> | Failure<SecureCredentialsError>>

Remove a specific credential

| Param | Type | | ------------- | --------------------------------------------------- | | options | { service: string; username: string; } |

Returns: Promise<Failure<SecureCredentialsError> | Success<boolean>>

removeCredentials(...)

removeCredentials(options: { service: string; }) => Promise<Success<boolean> | Failure<SecureCredentialsError>>

Remove all credentials belonging to a service

| Param | Type | | ------------- | --------------------------------- | | options | { service: string; } |

Returns: Promise<Failure<SecureCredentialsError> | Success<boolean>>

setCredential(...)

setCredential(options: { service: string; credential: Credential; options: CredentialOptions; }) => Promise<Success<boolean> | Failure<SecureCredentialsError>>

Set a credential into the secure store. This will overwrite any existing credential of the same service and username.

| Param | Type | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | options | { service: string; credential: Credential; options: CredentialOptions; } |

Returns: Promise<Failure<SecureCredentialsError> | Success<boolean>>

availableSecurityStrategies()

availableSecurityStrategies() => Promise<Success<SecurityStrategy[]> | Failure<SecureCredentialsError>>

Returns the available strategies for storing credentials, sorted strongest to weakest.

Returns: Promise<Failure<SecureCredentialsError> | Success<SecurityStrategy[]>>

supportedBiometricSensors()

supportedBiometricSensors() => Promise<Success<BiometricSensors>>

Determine the device capabilities for biometric scanning features. A device may have any combination of sensors and the sensors available may change depending on whether a user has granted permission to inspect the device sensors or whether they are enrolled with those sensors. Not all devices advertise what sensors they have. The information gathered is not guaranteed to be 100% accurate.

Returns: Promise<Success<BiometricSensors>>

Interfaces

Success

| Prop | Type | | ------------- | ----------------- | | success | true | | result | T |

Credential

| Prop | Type | | -------------- | ------------------- | | username | string | | password | string |

Failure

| Prop | Type | | ------------- | ------------------ | | success | false | | error | E |

SecureCredentialsError

| Prop | Type | | ------------- | --------------------------------------------------------------- | | code | SecurityErrorCode | | message | string |

CredentialOptions

| Prop | Type | | -------------- | --------------------------------------------------------------------- | | strategy | SecurityStrategyName |

SecurityStrategy

| Prop | Type | | ---------------- | --------------------------------------------------------------------- | | name | SecurityStrategyName | | level | SecurityLevel | | biometrics | boolean |

BiometricSensors

| Prop | Type | | ----------------- | -------------------- | | face | boolean | | fingerprint | boolean | | iris | boolean |

Type Aliases

SecurityStrategyName

Opaque<'SecurityStrategyName', string>

Opaque

T & { TYPE: K }

Enums

SecurityErrorCode

| Members | Value | | -------------------- | ------------------------------- | | FailedToAccess | 'failed to access' | | NoData | 'no data' | | Unknown | 'unknown' | | Unavailable | 'unavailable' | | Params | 'params' |

SecurityLevel

| Members | Value | Description | | ----------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | L1_Encrypted | 1 | The credential will be stored encrypted, but it can be accessed by the application while the device is locked. | | L2_DeviceUnlocked | 2 | The credential will be stored encrypted, and it can only be accessed by the application when the device is unlocked. | | L3_UserPresence | 3 | The credential will be stored encrypted, and it can only be accessed by the application after the OS confirms the user is present by means of a challenge. The OS may remember that the user is present for a configured period of time after a device PIN challenge. |