Wonder Login for YOURLS

Security hardening for YOURLS login: audit logs, automatic IP/user lockouts, allowlists and blocklists, plus optional TOTP two-factor authentication.

Version 1.0 · maintained by Wonder · MIT License

Screenshot / 界面截图

Features

• Records successful and failed username/password authentication attempts from the web interface and API, including UTC time, username, client IP, reason, authentication method, and User-Agent.
• Filters login logs by result, exact username, exact IP address, reason, and UTC date range.
• Deletes failed, successful, all, or retention-expired log entries.
• Automatically locks an IP address, a username, or both after a configurable number of failures within a configurable detection window.
• Supports exact IPv4/IPv6 addresses and CIDR ranges in IP allowlists and blocklists.
• Supports username allowlists and blocklists, manual locks, permanent locks, timed locks, and immediate unlock.
• Adds optional per-user RFC 6238 TOTP with a ±30-second clock-skew window, replay prevention, and eight single-use recovery codes.
• Encrypts TOTP secrets at rest with Sodium Secretbox or AES-256-GCM, using a key derived from YOURLS_COOKIEKEY.
• Resolves X-Forwarded-For from right to left only when the direct source is in the trusted-proxy list, preventing clients from selecting a spoofed IP.
• Ships seven interface languages: English, Simplified Chinese, French, Russian, Japanese, Spanish, and Brazilian Portuguese.

The plugin never records passwords, TOTP codes, recovery codes, or plaintext TOTP secrets.

Requirements and compatibility

• A private YOURLS installation with the standard plugin API.
• A recent PHP build with Sodium or OpenSSL when TOTP is used.
• MySQL/MariaDB with InnoDB and utf8mb4 support.

Version 1.0 is developed and tested against YOURLS 1.10.4 and PHP 8.5.9. It uses only documented YOURLS plugin hooks and does not modify core files.

Installation

1. Copy this repository to:

   YOURLS_ROOT/user/plugins/wonder-login-for-yourls
   

2. Open YOURLS Admin → Manage Plugins and activate Wonder Login for YOURLS.

3. Open Plugins → Login Security and review the defaults.

4. If YOURLS is behind a reverse proxy, configure the proxy address before relying on IP-based lockouts. See Reverse proxies.

5. Enable TOTP separately for each desired user. TOTP is not enabled automatically during installation or upgrade.

Activation creates these tables using the configured YOURLS_DB_PREFIX:

• wl4y_login_log
• wl4y_locks

Plugin settings and encrypted TOTP records are stored through the YOURLS Options API.

Default policy

Setting	Default
Failed-attempt threshold	5
Detection window	15 minutes
Lock duration	60 minutes
Automatically lock IP addresses	Enabled
Automatically lock users	Enabled
Login-log retention	180 days
Trusted proxies	Empty
Allowlists and blocklists	Empty

Automatic cleanup runs at most once per day. Expired locks and log entries older than the retention period are removed.

Lockout behavior

Only these failure reasons count toward automatic lockouts:

• invalid username or password;
• missing TOTP/recovery code;
• invalid TOTP/recovery code;
• reuse of an already accepted TOTP code.

Attempts rejected by an existing lock or blocklist are logged but do not extend the lock. An IP allowlist bypasses only IP locks and the IP blocklist; a user allowlist bypasses only user locks and the user blocklist. Allowlists do not bypass TOTP.

The login response remains the generic YOURLS credential error, so the plugin does not reveal whether a username exists, has TOTP enabled, or is locked.

Reverse proxies

By default, the plugin uses REMOTE_ADDR and ignores forwarded headers. When YOURLS is behind a proxy:

1. Add the direct proxy address or CIDR to Trusted proxy IP/CIDR.
2. Confirm that the proxy appends the client chain to X-Forwarded-For.
3. Do not add public client networks or 0.0.0.0/0 to the trusted-proxy list.

When the direct source is trusted, the plugin walks X-Forwarded-For from right to left and selects the first untrusted valid address. Exact IPv4 and IPv6 addresses are normalized before locks are compared.

TOTP enrollment and recovery

1. In Plugins → Login Security, choose a YOURLS user.
2. Select Generate or replace TOTP secret.
3. Add the displayed secret to a time-based authenticator.
4. Submit the current six-digit code within 10 minutes.
5. Save the eight recovery codes immediately. They are shown only once.

TOTP is enforced only after enrollment has been verified. Each accepted TOTP counter can be used once, and each recovery code is removed after use.

TOTP protects interactive web username/password login. YOURLS API signature authentication remains unchanged. API username/password attempts are still logged and are subject to IP/user lockouts, but do not require TOTP.

Changing YOURLS_COOKIEKEY makes existing encrypted TOTP secrets unreadable. Disable and re-enroll TOTP for affected users after such a key rotation.

Emergency access

If an administrator loses every second factor, deactivate the plugin from a trusted server-side context, regain access, then re-enable and reconfigure TOTP. Deactivation deliberately preserves settings, logs, locks, and TOTP data; it does not drop tables or delete options.

Languages

YOURLS loads the catalog matching YOURLS_LANG from translations/.

Language	YOURLS locale	Catalog
English	en_US	wonder-login-for-yourls-en_US.mo
Simplified Chinese	zh_CN	wonder-login-for-yourls-zh_CN.mo
French	fr_FR	wonder-login-for-yourls-fr_FR.mo
Russian	ru_RU	wonder-login-for-yourls-ru_RU.mo
Japanese	ja	wonder-login-for-yourls-ja.mo
Spanish	es_ES	wonder-login-for-yourls-es_ES.mo
Brazilian Portuguese	pt_BR	wonder-login-for-yourls-pt_BR.mo

For example, in user/config.php:

define( 'YOURLS_LANG', 'zh_CN' );

English source strings remain the fallback if a catalog is missing or the locale is not configured.

Rebuilding translation catalogs

The repository includes a dependency-free deterministic builder. It verifies that every PHP source string has a translation, writes PO/POT files, and compiles GNU MO files:

python tools/build_translations.py

Do not edit generated MO files directly. Update the aligned translations in tools/build_translations.py, run the builder, and commit the PO and MO output.

Data model and security notes

• All plugin functions, options, tables, form fields, and CSS selectors use the unique wl4y prefix.
• Every state-changing admin form uses a YOURLS nonce.
• Database values are passed through Aura.SQL parameter binding; table names are derived from the validated YOURLS database prefix.
• TOTP enrollment requires a valid current code before enforcement starts.
• Recovery codes are stored with password_hash(), not reversibly encrypted.
• TOTP secrets are never displayed again after verified enrollment.
• Usernames and lock values use binary collation to preserve exact matching.
• The plugin applies no TOTP requirement to cookie checks or API signatures.

Development references

• YOURLS plugin development
• YOURLS hooks
• YOURLS form security
• YOURLS database queries
• YOURLS internationalisation

中文说明

Wonder Login for YOURLS 1.0 提供登录审计、IP/用户自动锁定、黑白名单和按用户启用的 TOTP 双因素认证，不修改 YOURLS 核心文件。

安装时将整个仓库目录复制到 user/plugins/wonder-login-for-yourls，在 YOURLS 后台启用插件，然后打开 “插件 → 登录安全”。默认策略是在 15 分钟内失败 5 次后同时锁定 IP 和用户 60 分钟， 登录日志保留 180 天。

若站点位于反向代理之后，必须把直连代理的 IP/CIDR 加入“可信代理 IP/CIDR”；插件只有在 直连来源可信时才解析 X-Forwarded-For。不要把公网用户网段或 0.0.0.0/0 设置为可信 代理。

TOTP 必须针对每个用户单独生成并验证。验证成功前不会启用，启用时会生成 8 个只显示 一次的恢复码。TOTP 只保护网页用户名/密码登录，不改变 YOURLS API 签名认证。修改 YOURLS_COOKIEKEY 后，需要为已启用的用户重新配置 TOTP。

停用插件不会删除设置、日志、锁定或 TOTP 数据，以避免误操作造成审计记录丢失。

License

Copyright © 2026 Wonder. Released under the MIT License.