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\nsent out"]

    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 (a primary biometric and a PIN fallback) before first use.

Graduated lockout — biometric failure sequence¶

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); recovery flow (circle vouch, PIN reset).

What is suspended: reading Circle messages; viewing the 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:

"[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 impersonating the user remotely.
Pull-based recovery — restoration requires a Circle member to initiate it, not something triggerable 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 — 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. 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 differ from the normal PIN by at least 2 digits; cannot be a simple reversal (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 approving independently. Works offline as long as members are reachable; 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 it has a verified badge. Higher trust standard; actions logged.
Path 3 — Recovery phrase card (offline). A 12-word recovery phrase displayed once at onboarding, encouraged to be written on a card and stored separately. Re-derives the DID key and restores Circle memberships. Appropriate for users with a stable location to store a card; offer it but do not require it.
Path 4 — BNI support channel (last resort). Human-assisted recovery for users who have lost device, PIN, and recovery contacts. Requires government-issued ID or equivalent and has a 48-hour review window.

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