Idle Lock

• The profile and the access token are hidden.
• Every protected call and every refresh fails with a “session locked” error.
• On unlock, the SDK restores the session from the secure store, without a network call.

​

Requirements

​

How it works

1. Create the lock with a threshold, the number of seconds the app can stay in the background before it locks, and start it.
2. Set a passcode after sign-in. The lock does nothing until a passcode is set, so there is always a way back in. Show a “set a passcode” screen while no passcode is set.
3. Optionally enable biometrics as a shortcut past the passcode.
4. The app goes to the background. When it comes back after more than the threshold, the SDK seals the client and reports the lock as locked. Show your lock screen.
5. The user unlocks with the passcode or with biometrics. The SDK unseals the client and the session continues.
6. On sign-out, disable the lock. This forgets the passcode and the biometric shortcut.

​

Platform setup

<key>NSFaceIDUsageDescription</key>
<string>Unlock the app with Face ID.</string>

dependencies {
    implementation("androidx.biometric:biometric:1.1.0")
}

"ios": {
  "infoPlist": {
    "NSFaceIDUsageDescription": "Unlock the app with Face ID."
  }
}

​

Create and start the lock

import PreludeAuth

let idleLock = PreludeIdleLock(
    client: client,
    threshold: 60,                       // seconds in the background
    unlockReason: "Unlock to continue"   // shown on the Face ID / Touch ID sheet
)
idleLock.start()

import so.prelude.android.auth.lock.PreludeIdleLock

val idleLock = PreludeIdleLock(
    client = client,
    thresholdMs = 60_000L,               // time in the background
    unlockTitle = "Unlock to continue",  // shown on the biometric prompt
)
idleLock.start()

const idleLock = client.idleLock({
  thresholdSeconds: 60,
  unlockReason: "Unlock to continue", // shown on the biometric prompt
});
await idleLock.start();

const { isLocked, isEnabled, isBiometricsEnabled, isBiometricsAvailable } = idleLock.getState();
const unsubscribe = idleLock.subscribe(() => render(idleLock.getState()));

​

Set the passcode

try idleLock.setPasscode(passcode)

idleLock.setPasscode(passcode)

await idleLock.setPasscode(passcode);

​

Enable biometrics

if idleLock.isBiometricsAvailable {
    try idleLock.enableBiometrics()
}
// later: idleLock.disableBiometrics()

if (idleLock.isBiometricsAvailable) {
    idleLock.enableBiometrics()
}
// later: idleLock.disableBiometrics()

if (idleLock.getState().isBiometricsAvailable) {
  await idleLock.enableBiometrics();
}
// later: await idleLock.disableBiometrics();

​

Unlock

do {
    try await idleLock.unlock(passcode: passcode)
} catch PreludeAuthError.invalidPasscode(let message) {
    // Wrong passcode; the message says how many attempts remain.
} catch PreludeAuthError.lockedOut {
    idleLock.disable()
    try await client.logout()
}

// Biometrics (Face ID / Touch ID):
try await idleLock.unlockWithBiometrics()

try {
    idleLock.unlock(passcode)
} catch (e: PreludeAuthError.InvalidPasscode) {
    // Wrong passcode; the message says how many attempts remain.
} catch (e: PreludeAuthError.LockedOut) {
    idleLock.disable()
    client.logout()
}

// Biometrics, from a FragmentActivity:
idleLock.unlockWithBiometrics(activity)

import { InvalidPasscodeError, LockedOutError } from "@prelude.so/react-native-auth-sdk";

try {
  await idleLock.unlock(passcode);
} catch (e) {
  if (e instanceof InvalidPasscodeError) {
    // Wrong passcode; the message says how many attempts remain.
  } else if (e instanceof LockedOutError) {
    await idleLock.disable();
    await client.logout();
  }
}

// Biometrics:
await idleLock.unlockWithBiometrics();

​

Sign out

​

React hooks

import {
  Locked,
  PreludeAuthProvider,
  SignedIn,
  SignedOut,
  useIdleLock,
} from "@prelude.so/react-native-auth-sdk/react";

export default function App() {
  return (
    <PreludeAuthProvider
      options={{ endpoint }}
      idleLock={{ thresholdSeconds: 60, unlockReason: "Unlock to continue" }}
    >
      <SignedOut><LoginScreen /></SignedOut>
      <Locked><LockScreen /></Locked>
      <SignedIn><Home /></SignedIn>
    </PreludeAuthProvider>
  );
}

function LockScreen() {
  const { unlock, unlockWithBiometrics, isBiometricsEnabled, pending, error } = useIdleLock();
  // A passcode field that calls unlock(passcode), and a biometrics button:
  // {isBiometricsEnabled && <Button title="Use biometrics" onPress={unlockWithBiometrics} />}
}

• While the session is locked, useAuth().stage is "locked" and user is null, so SignedIn unmounts and Locked renders.
• In Home, show a passcode setup while useIdleLock().isEnabled is false.
• Hook actions never throw: a wrong passcode lands in useIdleLock().error. On LockedOutError the provider signs the user out.
• Every path that ends the session (signOut, a rejected refresh, a launch with no session) forgets the passcode.

​

Errors

​

Test on a simulator or emulator

• iOS Simulator: setting a passcode needs PreludeAuth 0.8.1 or later (React Native 0.8.1 or later). For biometrics, turn on Features > Face ID > Enrolled. The simulator does not show the Face ID sheet for the biometric unlock, so test the face check itself on a device.
• Android emulator: set a screen lock and enroll a fingerprint in Settings > Security, then touch the sensor from the emulator’s extended controls (Fingerprint), or with adb -e emu finger touch 1.