Authentication & Lockout Design¶

Specifications for MPowerUP authentication, the biometric lockout system, duress mode, and recovery paths.

Authentication model¶

MPowerUP uses a layered authentication model. Any registered modality succeeds — the user is never dependent on a single method.

flowchart TD
    OPEN["App opened"]
    GRACE{"Within grace\nperiod?"}
    AUTH{"Authentication\nrequired"}
    BIO["Biometric\n(fingerprint / face / voice)"]
    PIN["PIN fallback"]
    SUCCESS["Full access"]
    FAIL1["1st failure"]
    FAIL2["2nd consecutive\nfailure"]
    FAIL3["3rd consecutive\nfailure"]
    EMERGENCY["Emergency-only\nmode"]
    NOTIFY["Circle notification\nsentout"]

    OPEN --> GRACE
    GRACE -->|"yes"| SUCCESS
    GRACE -->|"no"| AUTH
    AUTH --> BIO
    AUTH --> PIN
    BIO -->|"success"| SUCCESS
    PIN -->|"success"| SUCCESS
    BIO -->|"fail"| FAIL1
    FAIL1 -->|"retry"| FAIL2
    FAIL2 -->|"offer PIN\nretry"| FAIL3
    FAIL3 --> EMERGENCY
    EMERGENCY --> NOTIFY

Registered modalities¶

Modality	Notes
Fingerprint	Default where hardware supports it
Face ID	Registered at onboarding as alternative
Voice passphrase	Registered at onboarding; useful in low-dexterity situations
PIN (4–6 digit)	Always available as fallback; never disabled

Users register a minimum of two modalities at onboarding. The onboarding flow prompts for a primary (biometric) and a fallback (PIN) before first use.

Graduated lockout — biometric failure sequence¶

Failure progression¶

Consecutive failures	Response	Rationale
1	Silent — no action	Everyone misses biometrics occasionally
2	Soft prompt — offer PIN fallback	Pattern detected; reduce friction before escalating
3	Emergency-only mode + circle notification sent	Probable unauthorised access attempt
5	Suppress circle member list and contact details from display	Device may be in attacker hands; protect the circle

A successful login at any point resets the counter to zero.

Emergency-only mode¶

When the lockout threshold is reached, the app transitions to emergency-only mode. The user or device holder retains access to safety tools but cannot read or reveal circle data.

What remains accessible¶

One-tap 911 / local emergency services
One-tap distress beacon to circle (GPS coordinates + timestamp only — no message content)
Crisis hotline shortcuts (configurable at onboarding: domestic violence line, crisis text line, local shelter)
Recovery flow (circle vouch, PIN reset)

What is suspended¶

Reading circle messages
Viewing circle member list and contact details
Posting help requests
Any function that reveals who is in the circle

The asymmetry is intentional. The locked-out session can send outbound safety signals but cannot read inbound circle data. An attacker in possession of the device cannot use emergency mode to harvest the user's support network.

Circle notification¶

When emergency-only mode activates, all circle members receive a notification:

"[Name]'s device has had 3 consecutive failed logins and is now in emergency-only mode.

We recommend physically locating [Name] to confirm they have their device and that the login attempts were their own. Do not share circle information until identity is confirmed in person.

Once you have confirmed this is [Name], tap I've confirmed this is [Name] to restore full access."

Design decisions in this message¶

"Physically locating" is intentional — for this population, in-person confirmation is more reliable than any remote verification
"Do not share circle information" prevents the notification itself from being used by an attacker to extract circle data by impersonating the user remotely
Pull-based recovery — restoration requires a circle member to initiate it, not something that can be triggered by whoever has the device

Duress mode¶

A duress PIN is a secondary PIN that appears to log in normally but activates a hidden distress state. This is a standard pattern in domestic violence and coercion safety technology.

Behaviour when duress PIN is entered¶

App opens and appears fully functional
Circle messages shown are a stripped-down view — recent low-sensitivity messages only, no location data, no help requests
A silent distress signal is sent to one or more designated duress contacts in the circle — distinct from the general circle notification
Session is recorded (timestamps, screens viewed) for review by the duress contact later
No visual indicator that duress mode is active — the person watching must not know

Duress contact designation¶

At onboarding, the user designates one or more circle members as duress contacts. These are the people who would be trusted to act if the user is in danger. They receive duress signals via a separate notification channel and are trained (via in-app guidance) on how to respond.

Duress PIN setup rules¶

Must be different from the normal PIN by at least 2 digits
Cannot be a simple reversal of the normal PIN (e.g. 1234 → 4321)
Stored and verified locally, never transmitted

Recovery paths¶

Standard account recovery (email + magic link) does not work for users without reliable email access. BNI uses a layered recovery system:

Path 1 — Circle vouch (primary)¶

Two or more circle members confirm the user's identity through the app. Each approves a recovery request independently. On approval, a new session token is issued and the device re-authenticates.

Works offline as long as circle members are reachable
Does not require email or internet beyond peer connectivity
Resistant to social engineering — requires multiple independent confirmations

Path 2 — Trusted organisation account¶

A verified organisation in the circle (social worker, shelter, mutual aid group) can initiate recovery with a single approval if they have a verified badge. Organisations are held to a higher trust standard and their recovery actions are logged.

Path 3 — Recovery phrase card (offline)¶

At onboarding, the user is issued a 12-word recovery phrase displayed once. They are encouraged to write it on a card and store it separately from the device. This phrase can re-derive the DID key and restore circle memberships.

Appropriate for users with a stable location to store a physical card
Not appropriate for all houseless users — offer it but do not require it

Path 4 — BNI support channel (last resort)¶

For users who have lost everything — device, PIN, and recovery contacts — a human-assisted recovery channel through BNI support. This path requires government-issued ID or equivalent identity verification and has a 48-hour review window.

Recovery path comparison¶

Path	Requires internet	Requires email	Requires physical ID	Speed
Circle vouch	Yes (peer)	No	No	Minutes
Organisation account	Yes	No	No	Minutes
Recovery phrase	No	No	No	Instant
BNI support	Yes	No	Yes	48 hours

RlivN — authentication model¶

The RlivN client tablet has no user-facing authentication. The tablet itself is the authenticated device, enrolled via MDM (Mobile Device Management) at setup.

Interface	Authentication
Client tablet	None — device-level trust via MDM enrollment. The tablet IS the identity. Physical security replaces software authentication.
Caregiver portal	Full biometric + 2FA (TOTP or hardware key). Session expires after 2 hours of inactivity. Login from new device triggers family notification.
Family read-only view	Email + magic link. Read-only — cannot change configuration.

Session audit log (caregiver portal)¶

All caregiver configuration changes are logged with: - Timestamp - Change description - IP address and device fingerprint - Whether the change was reviewed by a family account

The audit log is readable by family accounts and cannot be deleted by the caregiver. This is the primary safeguard against caregiver abuse.