docs: add README + setup screenshot; add .gitignore, untrack build/gradle artifacts

2026-06-19 09:08:35 +00:00
parent 62d7c929fe
commit 70ac1cd90e
2847 changed files with 64 additions and 325978 deletions
@@ -0,0 +1,51 @@
+# Homelab MFA
+
+Biometric push-approval for your homelab logins. When you sign in through Authentik, your phone
+buzzes — approve with a fingerprint, or deny with one tap. A self-hosted alternative to Duo /
+Authy push, with **no third-party cloud** in the loop.
+
+## How it works
+
+1. You log in via **Authentik**. A flow step fires an **ntfy** notification to your phone with two
+   action buttons: **Approve** and **Deny**.
+2. The buttons are `homemfa://approve?token=…` / `homemfa://deny?token=…` deep links that open this app.
+3. **Approve** triggers a biometric prompt (fingerprint / face / device PIN). On success the app
+   POSTs `approve:<token>` to `ntfy.khodak.me/mfa-approve`; your Authentik flow is listening on that
+   topic and completes the login.
+4. **Deny** POSTs `deny:<token>` to `mfa-deny` and blocks the login — no biometric needed to reject.
+
+The activity is `showWhenLocked` + `turnScreenOn`, so an approval works straight from the lock screen.
+
+## Features
+
+- **Biometric gate** — `BIOMETRIC_STRONG` or device credential required to approve (deny is instant)
+- **Lock-screen ready** — wakes the screen and shows over the keyguard
+- **Self-hosted** — talks only to your own ntfy instance; no Firebase, no vendor cloud
+- **Zero stored secrets** — stateless; each request carries a one-time token
+- **Setup self-check** — a "Test Biometric" button confirms enrollment before you rely on it
+
+## Screenshots
+
+<p align="center">
+  <img src="docs/screenshots/setup.png" width="240" alt="Setup screen">
+</p>
+
+## Install
+
+1. Download `homelab-mfa.apk` from the [latest release](../../releases/latest)
+2. On your Android phone: **Settings → Apps → Install unknown apps** → allow your browser/file manager
+3. Open the APK and tap Install
+4. Open **Homelab MFA** and tap **Test Biometric** to confirm your fingerprint is enrolled
+
+## Server side
+
+You need:
+
+- An **ntfy** instance reachable at `ntfy.khodak.me` (or change the host in `MainActivity.kt`)
+- An **Authentik** flow that, on login, publishes a notification with the two `homemfa://` action
+  buttons, then waits on the `mfa-approve` / `mfa-deny` topics for the decision
+
+## Requirements
+
+- Android 9.0+ (API 28)
+- A fingerprint, face, or device PIN enrolled