luci-app-2fa: init checkin

[Tokisaki-Galaxy]

• This PR is not from my main or master branch 💩, but a separate branch ✅
• Each commit has a valid ✒️ Signed-off-by: <my@email.address> row (via git commit --signoff)
• Each commit and PR title has a valid 📝 <package name>: title first line subject for packages
• (N/A) Incremented 🆙 any PKG_VERSION in the Makefile
• Tested on: (architecture, openwrt version, browser) ✅
• ( Preferred ) Screenshot or mp4 of changes:
• ( Optional ) Closes:
  [POC,WIP] Implement 2-Factor Authentication with TOTP or HOTP #7069
  Feature request: Support for Passkey (WebAuthn) authentication in LuCI #8273
• ( Optional ) Depends on: openwrt/luci luci-base: add generic authentication plugin (login HOOK) #8281
• Description: (describe the changes proposed in this PR)

2026-02-04.180055.mp4

the app must changed LuCI core file because:

• No hook point exists between password verification and session creation
• External packages cannot inject authentication logic
• No plugin discovery mechanism in the original code

---

Security Measures

Constant-time string comparison to prevent timing attacks
Username sanitization to prevent command injection
Array-based popen to prevent shell injection
OTP format validation (exactly 6 digits)
Session destroyed if 2FA verification fails
Uses authenticated session username to prevent bypass attacks

origin repo https://github.com/Tokisaki-Galaxy/luci-app-2fa

[Neustradamus]

@Tokisaki-Galaxy: Nice, good job!

Do not forget to solve:

🔶 Author name (Tokisaki-Galaxy) seems to be a nickname or an alias
🔶 Committer name (Tokisaki-Galaxy) seems to be a nickname or an alias

[stangri]

Looks very polished @Tokisaki-Galaxy!

Does this use TOTP? If the OpenWrt device doesn't have RTC and is offline or generally doesn't have correct time, does SSH become the only option to login?

Is there a README/instructions (ideally a hint on failed attempt) on how to disable 2FA from SSH/CLI for people who may be locked out of WebUI and can't read code ahead of time?

[Tokisaki-Galaxy]

@stangri

Please refer to the newly added video at the top of the description section for details.

The plugin can choose either TOTP or HOTP, but TOTP is recommended.
For RTC clock that is not synchronized (for example, the year is 1970), users can choose the 2fa behavior (strict mode) through options. By default, LAN areas are allowed to bypass 2FA for login, while non-LAN areas are prohibited. It can be configured to allow anyone to bypass 2FA for login.

Regarding the documentation for SSH/CLI, I'm not quite sure where it should be placed. Should it be directly included in the web UI? But if users don't read it carefully, they might not be able to log in and it would be impossible to see the result. Do you have any suggestions?

Previously, it was planned to add backup code, but this was abandoned because it would cause the bitward auto-fill function to become unusable and the complexity would be too high.

[systemcrash]

@Tokisaki-Galaxy let's see whether the plugin structure needs some modifications to handle 2FA stuff.

[Tokisaki-Galaxy]

@systemcrash
branch have update

[Tokisaki-Galaxy]

Refactored generate_otp.uc to leverage ucode native modules and built-in features. replaces the manual implementations, improving performance

[systemcrash]

OK - since it's an auth plugin, let's house it in the plugin folder.

[systemcrash]

There is also the trick that the system uses - it sets the minimum clock value to the last file-change time found in the /etc FS. Check openwrt/package/base-files/files/etc/init.d/sysfixtime for how it works. If this is available as a 'fallback', that's also not bad.

[github-actions]

Warning

Some formality checks failed.

Consider (re)reading submissions guidelines.

Failed checks

Issues marked with an ❌ are failing checks.

Commit 2bb8966

• 🔶 Commit(ter) name must be either a real name 'firstname lastname' or a nickname/alias/handle
  Actual: GitHub seems to be a nickname or an alias
  Expected: a real name 'firstname lastname'

Commit 6dd1bea

• 🔶 Commit(ter) name must be either a real name 'firstname lastname' or a nickname/alias/handle
  Actual: GitHub seems to be a nickname or an alias
  Expected: a real name 'firstname lastname'

For more details, see the full job log.

_{Something broken? Consider providing feedback.}