Sessions, Authentication, and Multi-Device Support

Logging in

To import an existing wallet, the user first needs to log in to an existing device to initiate the session, obtain the userId, and set up new biometrics. This is typically required for a new device, but it can be done at any point. The Add this Device Flow within the Capsule Popup implements this logic.

Session management

By default, the Capsule SDK implements getChallengeStorage, which abstracts away session management. However, this function can be overridden if preferred to manually manage the session. Here is more information on how Capsule sessions work if you wish to do this:
Remember, there is a Capsule signer stored within Capsule’s cloud. The Capsule signer will not provide a signature without a valid cookie, which expires every 5 minutes. The cookie is initiated while setting up the account, verifying the code, and adding the secp256r1 public key. To recreate the cookie, the Capsule server sends a challenge under an unprotected endpoint, and only after sending the correct secp256r1 signature returns a cookie.
The signing logic is included in ChallengeStorage and an appropriate implementation is provided in React Native using a keychain. The secp256r1 curve was selected for this purpose as it is supported by the Apple and Android secret management systems.

Wallet Login

Capsule strives to deliver a smooth and secure login process that respects user convenience and the application developers' requirements. The login flow, facilitated through the Capsule client, is designed to be minimalistic yet highly secure, integrating biometric authentication for enhanced user identification and verification.

Collecting a Session Token

The process begins with the user's device collecting a session token. This action is performed using biometric authentication, such as facial recognition or fingerprint scanning, which helps provide a robust layer of security. In this process, a timestamped request is signed using the device's hardware enclave, a secure and isolated environment within the device that protects sensitive data and processes from potential threats.

Signature Verification and Session Token Retrieval

The signed, timestamped request is then sent to the Capsule server. Here, the signature is thoroughly verified, and upon successful validation, an app-specific session token is issued. This session token, unique to the application and user, grants the application the ability to sign application-specific transactions with the custodial key for a limited time duration. This setup provides an added layer of security as the permissions granted by the token are time-bound, limiting potential misuse.
Through this login process, Capsule ensures that user identity is securely verified and that the application can carry out its operations within a safe and controlled environment. Capsule's commitment to providing a secure and minimally intrusive login process creates a balance between security and usability, contributing to an optimal user experience.