From 02a4663ce1e097a43dca19b38d66e6e23648cdf5 Mon Sep 17 00:00:00 2001
From: Zhixuan Jiang <alexjiang20232024@gmail.com>
Date: Sun, 26 Jul 2026 11:35:32 -0400
Subject: [PATCH] docs(auth): document passkey deployment

- Explain enablement, credential compatibility, and management behavior.\n- Document exact HTTPS origin and single-process challenge-store requirements.\n\nCo-authored-by: Codex <267193182+codex@users.noreply.github.com>
---
 pages/guide/advanced/passkeys.md | 91 ++++++++++++++++++++++++++++++++
 1 file changed, 91 insertions(+)
 create mode 100644 pages/guide/advanced/passkeys.md

diff --git a/pages/guide/advanced/passkeys.md b/pages/guide/advanced/passkeys.md
new file mode 100644
index 000000000..a697e377f
--- /dev/null
+++ b/pages/guide/advanced/passkeys.md
@@ -0,0 +1,91 @@
+---
+title:
+  en: Passkeys
+  zh-CN: 通行密钥
+categories:
+  - guide
+  - advanced
+top: 109
+---
+
+## Enable and manage passkeys { lang="en" }
+
+## 启用和管理通行密钥 { lang="zh-CN" }
+
+::: en
+
+An administrator must enable the global `webauthn_login_enabled` setting before users
+can register or sign in with passkeys. Each signed-in user can then open their profile to register, name,
+rename, review, or revoke credentials. Password, LDAP, SSO, and recovery methods remain
+available.
+
+Disabling the setting hides passkey login and management in the supported UI and rejects
+new registration and login ceremonies. It does not delete stored credentials. Re-enabling
+the setting makes them available again.
+
+Credentials created by earlier OpenList versions remain valid. They appear with a
+generated name and unknown creation metadata until renamed; `last_used_at` is populated
+after a successful assertion. No database migration or credential re-registration is
+required.
+
+:::
+
+::: zh-CN
+
+管理员必须先启用全局设置 `webauthn_login_enabled`，用户才能注册通行密钥或使用通行密钥登录。
+登录后的用户可以在个人资料中注册、命名、重命名、查看或撤销凭据。密码、LDAP、SSO
+和恢复方式仍然可用。
+
+关闭该设置后，受支持的界面会隐藏通行密钥登录和管理功能，并拒绝新的注册和登录流程，
+但不会删除已保存的凭据。重新启用后，这些凭据会再次可用。
+
+旧版 OpenList 创建的 WebAuthn 凭据仍然有效。它们会显示自动生成的名称，创建时间显示为
+未知，用户可以手动重命名；成功完成一次验证后会写入 `last_used_at`。无需执行数据库迁移，
+也无需重新注册凭据。
+
+:::
+
+## Deployment requirements { lang="en" }
+
+## 部署要求 { lang="zh-CN" }
+
+::: en
+
+- Production deployments must set `site_url` to the canonical absolute HTTPS URL that
+  users open, for example `https://files.example.com`.
+- WebAuthn validates the exact public origin (scheme, host, and port) and uses the
+  configured hostname as the RP ID. A different domain, HTTP outside localhost, or a
+  mismatched port is rejected.
+- A reverse proxy must preserve the public `Host` and `X-Forwarded-Proto: https` values.
+  Do not rewrite passkey requests to a different externally visible origin.
+- Challenges are server-side, one-time, and expire after five minutes. They are stored
+  in process memory; restarting OpenList invalidates only pending ceremonies, not saved
+  credentials.
+- Run a single OpenList process when passkeys are enabled. A multi-replica deployment
+  requires a shared challenge store with atomic consume semantics before enabling
+  passkeys.
+- User verification is required. OpenList does not silently fall back to a weaker
+  ceremony if the authenticator cannot verify the user.
+
+After changing `site_url` or proxy routing, complete a new registration and sign-in from
+the public URL to verify the final origin.
+
+:::
+
+::: zh-CN
+
+- 生产环境必须把 `site_url` 设置为用户实际访问的规范 HTTPS 绝对地址，例如
+  `https://files.example.com`。
+- WebAuthn 会严格验证公开来源（协议、主机和端口），并使用配置地址的主机名作为 RP ID。
+  域名不同、在 localhost 之外使用 HTTP，或端口不匹配时都会拒绝验证。
+- 反向代理必须保留公开的 `Host` 和 `X-Forwarded-Proto: https`。不要把通行密钥请求
+  改写为另一个对外可见的来源。
+- 质询保存在服务端、只能使用一次，并在五分钟后过期。质询存放在进程内存中；重启
+  OpenList 只会使正在进行的流程失效，不会删除已保存的凭据。
+- 启用通行密钥时应只运行一个 OpenList 进程。多副本部署必须先提供支持原子消费的共享
+  质询存储，然后才能启用通行密钥。
+- 必须完成用户验证。如果验证器无法验证用户，OpenList 不会静默降级到安全性更弱的流程。
+
+修改 `site_url` 或代理路由后，请从公开地址重新完成一次注册和登录，以验证最终来源。
+
+:::