【免费下载链接】fluxerA free and open source instant messaging and VoIP chat app built for friends, groups, and communities.项目地址https://gitcode.com/gh_mirrors/flu/fluxer点击查看免费下载Fluxer 是一套自托管的即时通讯与 VoIP 平台其 HTTP API、Gateway 与 Admin API 各自拥有严格的认证边界。本文以仓库文档 authentication.md 为骨架结合fluxer_api中的认证中间件与测试实现系统讲解Authorization头的四种凭证形态、各类令牌的格式与生命周期、401/403 错误码的精确语义、SSO 强制登录、账户状态门以及 sudo 模式帮助你在开发 Fluxer 客户端、机器人或管理工具时写出正确的认证代码。凭证处理原则Fluxer 的认证模型非常简单直接持有凭证即视为其所有者。因此文档对凭证的保管提出了硬性要求凭证不得进入日志、分析系统、崩溃报告或源码只在需要期间保留凭证用完即弃在不信任的网络传输时必须启用 TLS绝不把Authorization凭证放进 URL。对于 webhook token、签名媒体路径signed media paths和上传能力upload capability这三类URL 即凭证的场景必须把完整的 URL 当作秘密对待不得通过重定向、追踪参数或 referrer 泄露出去。Authorization 请求头Fluxer 规定一次请求只发送一个凭证放在Authorization头中令牌必须非空且不能带前后空白。Scheme 前缀区分大小写唯一的例外是机器人令牌相关两个路由见下文Bot tokens。授权方案Authorization schemes值名称说明Bot tokenBot token认证应用的机器人账户Bearer tokenOAuth2 访问令牌1由账户授权受令牌 scopes 限制token用户会话令牌不带 scheme 前缀直接发送Admin tokenAdmin API 密钥仅接受于/v1/admin路径之下权限受密钥及其所有者双重限制1有一个值处理方式不同Bearer flx_后跟 36 个字母数字字符时认证的是该值所指代的用户会话即用户会话令牌的另一种携带方式。每个受保护操作都会在自己的文档页面上声明接受哪几种凭证类型。认证失败使用标准 错误响应对象客户端必须只依据稳定的code字段做判断——message是本地化文案随时可能调整措辞。令牌格式所有已签发的令牌都应视为不透明值opaque value原样携带、不做解析、不做猜测。机器人令牌的内部结构是application_id.secret即应用 ID 与密钥的组合。有三个关键约束需要特别注意密钥只展示一次bot token、Admin API 密钥、client secret 在创建响应返回之后便无法再读取bot token 的预览preview不能用于认证请求。轮换立即生效轮换适用于 bot token 和 client secret轮换 bot token 会同时终止该 bot 持有的所有 Gateway 会话。Admin API 密钥不支持轮换只能吊销后重建。令牌必须按创建时的形态原样发送使用对应的 scheme。用户会话令牌用户会话令牌认证一个普通用户账户由 Authentication HTTP API 中的登录、注册与会话交换操作签发。其形态为字面前缀flx_加上恰好 36 个 base62 字符且该响应是读取它的唯一机会——丢失后只能重新认证。用户会话令牌同样被 Gateway 的 Identify 命令 接受。当需要 sudo 模式证明时通过独立的X-Fluxer-Sudo-Mode-JWT请求头补充见下文 sudo 模式。从实现上看AuthMiddleware.ts是整个 HTTP API 认证入口的核心LoginRequired 在没有解析出用户时直接抛出UnauthorizedError401并调用ensureOAuth2BearerRouteSupport检查路由是否接纳 OAuth2 bearer 凭证随后检查账户的异常活动标志位而 DefaultUserOnly 在user.isBot为真时抛出AccessDeniedError403正是用户专用操作拒绝机器人账户这条规则在源码层面的落点。Bot tokens机器人令牌Gateway 在 Identify 命令 中接受 bot token。HTTP 层有两个操作对 scheme 前缀大小写不敏感GET /v1/gateway/bot获取 Gateway 信息GET /v1/applications/me获取机器人应用信息其中GET /v1/applications/me严格要求Bot前缀任何其他形态都会返回 401INVALID_TOKENGET /v1/gateway/bot的具体认证行为见下文Gateway 认证。机器人的能力边界是单向的bot 不能调用仅限普通用户账户的操作此类调用返回 403ACCESS_DENIED。在 Authentication 中凡是从请求体或令牌中解析账户的操作——如登录、密码恢复、邮箱验证、邮箱还原、IP 授权——当解析出的账户是 bot 时统一返回403BOT_USER_AUTH_ENDPOINT_ACCESS_DENIED。OAuth2 access tokensOAuth2 访问令牌每个 OAuth2 访问令牌都归属于某个账户。Fluxer 支持**授权码authorisation code和刷新令牌refresh token**两种 grant。Bearer 语法见上表用户会话例外同样适用Bearer flx_ 36 字符视为会话令牌。关键规则只有显式支持 OAuth2 的操作才接受访问令牌不支持的用户操作对有效访问令牌返回 403ACCESS_DENIED。同时接受会话令牌与访问令牌的操作只在访问令牌上检查 scope。仅限 bearer 的操作bearer-only会以 401UNAUTHORIZED拒绝会话令牌、bot token 和 Admin API 密钥。scope 缺失返回403MISSING_OAUTH_SCOPE每个操作精确要求其命名的 scope。scopes、grant、刷新、吊销与 introspection 的完整定义见 OAuth2 HTTP API。Missing OAuth2 scope 响应体MISSING_OAUTH_SCOPE响应在code与message之外附带以下成员字段类型说明required_scopestring请求所缺少的 OAuth2 scopescope 的语义化核对也体现在测试中OAuth2ScopeEnforcement.test.ts与OAuth2ScopeMiddleware.test.ts位于 fluxer_api/src/api/oauth/testsBearerTokenScopeFiltering.test.ts位于 fluxer_api/src/api/user/tests共同验证了 scope 过滤与强制执行的边界行为。Admin API keysAdmin API 密钥Admin API 密钥以创建者的身份认证/v1/admin路径之下的请求权限同时受密钥自身与其创建者两者限制密钥持有自己的 ACL 集合从创建者账户移除 ACL 与从密钥移除 ACL 是两件独立的事。一次请求必须同时满足创建者拥有操作要求的 ACL或*通配且密钥自身拥有该 ACL或*——因此密钥权限永远不会超过其背后的账户。密钥的 secret 只返回一次丢失后只能吊销重建见 Admin API keys。除了密钥之外Fluxer 的 Admin 操作还接受用户会话令牌或 OAuth2 bearer 令牌但 bearer 令牌必须属于内置的 Admin OAuth2 应用来自其他应用的 bearer 一律返回 403ACCESS_DENIED携带 bot token 的请求返回 401UNAUTHORIZED。每个 Admin 请求都要求用户具备admin:authenticateACL 或通配符否则返回403MISSING_PERMISSIONS密钥认证的请求还需要密钥与其所有者同时具备操作所需的 ACL否则返回403MISSING_ACL。完整的 ACL 注册表与审计契约见 Admin API。从源码看AdminMiddleware.ts 的requireAdminAccess完整实现了上述链路先取ctx.get(user)判断是否未认证401ensureBearerIsBuiltInAdminApplication校验内置 Admin OAuth2 应用ensureAdminCanAuthenticate检查admin:authenticate或通配 ACLensureAdminApiKeyOwnerCanUseACLs对密钥所有者做二次 ACL 校验最后hasAnyAdminACL用请求方密钥或用户的 ACL 集合比对所需 ACL任一环节不满足即抛出对应的MissingACLError/UnauthorizedError。授权结果Authorisation outcomes每个受保护操作都会声明自己的认证策略Fluxer 将策略归为四类用户操作要求解析出用户拒绝未主动接纳的 OAuth2 bearer 凭证用户专用操作还拒绝 bot 账户。Bot 操作接受 bot token并把应用机器人账户解析为请求身份。OAuth2 操作要求Bearerscheme 与它命名的 scope。Admin 操作要求会话、Admin OAuth2 bearer 或 Admin API 密钥凭证外加所需 ACL。整个 API 中只有GET /v1/applications/me强制要求Bot前缀本身。凭证甚至会影响未认证操作它可以决定基于账户的限流档位也可以免除 CAPTCHA。每个操作都会单独文档化其对凭证的其他用途。错误码的分配规律非常清晰401UNAUTHORIZED凭证缺失、格式错误、未知、过期或已吊销bot token 访问 Admin 操作、非 bearer 凭证访问 bearer-only 操作也归入 401。403ACCESS_DENIED凭证有效但被操作策略拒绝Authentication 操作解析出 bot 账户时返回专门的 403BOT_USER_AUTH_ENDPOINT_ACCESS_DENIED。403MISSING_OAUTH_SCOPE/ 403MISSING_ACL/ 403MISSING_PERMISSIONSscope 与 Admin 权限类失败使用这些专门代码。401 响应不带WWW-Authenticate头客户端必须解析响应体中的code字段来区分失败原因。普通已认证操作还会叠加账户状态门见下文。此外文档建议客户端将无法识别的附加成员视为不存在且同一code在不同操作上可能携带不同的附加成员客户端只应读取自己操作所文档化的那些成员。单点登录强制SSO enforcement实例可以在配置并启用 SSO 后强制单点登录。强制生效期间下列 Authentication 操作 统一返回 403SSO_REQUIRED注册账户、密码登录获取可发现 WebAuthn 选项、WebAuthn 认证完成 TOTP 登录、获取 WebAuthn MFA 选项、完成 WebAuthn MFA 登录验证邮箱、重发邮箱验证请求密码恢复、校验密码重置令牌、重置密码还原邮箱变更授权 IP、重发 IP 授权、轮询 IP 授权获取用户名建议。两个补充细节当 SSO 回调中提供方声明的身份匹配不到任何现有账户、且实例未开启自动开通auto-provision时回调返回同样的SSO_REQUIRED。强制仅在上述操作处生效不影响已认证账户的改密或 MFA 管理开启强制后已签发的会话令牌、bot token、OAuth2 访问令牌与 Admin API 密钥全部继续有效。账户状态门Account state gates普通已认证操作会对存在未满足的可疑活动要求的账户返回403ACCOUNT_SUSPICIOUS_ACTIVITY。响应中每个置位的标志代表一个未满足的要求一旦满足该标志就不再出现在响应中。响应体字段类型说明dataobject其中suspicious_activity_flags成员为仍待处理的可疑活动标志位字段整数源码层面AuthMiddleware.ts 中的LoginRequired会调用getEffectiveSuspiciousFlags(user)当结果非 0 时抛出AccountSuspiciousActivityError而LoginRequiredAllowSuspicious则跳过该检查正是显式放行类路由的实现基础。显式接纳可疑账户的路由在要求未满足时仍接受凭证包括获取当前用户、修改当前用户获取当前用户设置邮箱变更流程含退信地址变体与邮箱验证重发手机验证流程会话列表与会话终止Applications 与 OAuth2 中的应用及授权管理操作。Admin 操作不应用可疑活动门。此外Fluxer 没有统一的已删除/已禁用账户拦截门每个读取账户状态的操作各自应用自己的规则而登录、密码与邮箱类操作会直接拒绝已删除账户。认证失败与 IP 封禁认证错误的响应不区分未知、过期、已吊销与格式错误的凭证——统一按授权结果一节中的错误码处理这是刻意设计避免向攻击者泄露凭证状态。反复认证失败可能触发IP 封禁。因此文档给出的操作建议非常直白停止重试被拒绝的凭证去获取一个新的。这与 AbusiveIpAutoBanner.ts 的实现互为印证该中间件对认证失败行为进行评分维护每个 IP 的distinctTokenHashes集合当同一 IP 上的失败得分或令牌多样性超过阈值时触发封禁并通过hashAuthTokencreateHash(sha256)取前 32 位十六进制对令牌做哈希存储——既不泄露令牌内容又能检测出同一 IP 反复尝试不同凭证的行为。Sudo 模式sudo 模式是一种短期证明它表明账户持有者刚刚重新验证过一项凭证。要求 sudo 模式的操作会在自己的页面上声明多因素认证文档定义了可接受的证明形式、sudo verification object 字段以及 403SUDO_MODE_REQUIRED时返回的 sudo mode methods object。有效期与携带方式sudo 证明有效期为五分钟。通过X-Fluxer-Sudo-Mode-JWT请求头携带。无效、过期或账户不匹配的令牌其响应与缺失令牌完全一致。源码实现位于 SudoModeService.ts使用jose签发HS256 JWTsub为用户 IDexp为签发时间 5 minutes验证时校验算法、type sudo与sub是否匹配当前用户。中间件 SudoModeMiddleware.ts 则负责读取请求头并调用该服务bot 账户直接判定为sudoModeValid: true未认证请求与未携带头的请求不做校验。谁可以获取 sudo 令牌Fluxer只为持有 TOTP secret 或已注册 WebAuthn 凭证的账户签发令牌仅有密码的账户每次需要 sudo 的操作都要重新验证只要注册了 passkey无论是否将 passkey 启用为第二因素都算数methods对象报告totp、webauthn与backup_codes没有 TOTP secret 的账户可以在mfa_method为totp下提交一张未消费的备用码backup code创建 WebAuthn 注册选项 与 禁用当前账户 两个操作不签发 sudo 令牌也不返回X-Fluxer-Sudo-Mode-JWT响应头bot 账户直接满足 sudo 模式没有密码、没有 TOTP secret、也没有注册 WebAuthn 凭证的账户同样直接满足。两个容易踩坑的细节sudo 证明覆盖该账户的全部会话——即使吊销了获取证明的那个会话证明在其过期前依然有效。当账户未能出示有效证明时操作返回 403SUDO_MODE_REQUIRED响应体带has_mfa与methods供客户端决定向用户展示哪种验证方式证明存在但错误时则返回 400INVALID_FORM_BODY及path: mfa_code、code: INVALID_MFA_CODE的校验错误。TOTP 路径还受15 分钟内 10 次多因素尝试的账户级配额约束且先扣配额再校验因此配额耗尽时正确的验证码也会被拒绝。这些负路径在 SudoModeNegativeCases.test.ts 中有完整的断言覆盖。Gateway 认证Gateway 与 HTTP API 的认证方式不同bot token 或用户会话令牌放在 Identify 命令 的token字段中而不是Authorization头且不带任何 HTTP 认证前缀。失败时的关闭行为无效或已吊销的凭证连接以关闭码4004关闭token字段缺失以4002关闭reason 为Invalid identify payload其余关闭码的完整定义见 opcodes-and-close-codes。另外HTTP 的 Get Gateway information 端点只校验 bot token 的形态大小写不敏感的前缀一次成功响应并不证明令牌真实有效。其他凭证面webhooks 与媒体代理并非所有受保护资源都走Authorization头Webhookswebhook 执行操作的标识与令牌放在请求路径中操作不接受Authorization凭证契约见 Webhooks。Media Proxy普通媒体或 relay 路由不读取Authorization头Media Proxy 概览。存储对象由其路径授权外部媒体由其路径签名授权relay 请求由 URL 中内嵌的**能力capability**授权契约见 Upload relay。在签名附件 URL 策略enforce模式下签名参数ex、is、hm与uc必须参与 URL 校验——这些 URL 本身就是秘密泄露 URL 等同于泄露读取权限。总结Fluxer 的认证体系可以用一句话概括一种凭证、一个请求头、一套精确的错误码。实践中请记住四条主线——发送凭证时严格匹配四种 scheme 形态Bot/Bearer/ 裸令牌 /Admin区分 401凭证本身无效与 403凭证有效但策略拒绝并只依赖code字段为敏感操作预留X-Fluxer-Sudo-Mode-JWT五分钟证明的获取与回传链路以及认清 Gateway、Webhook、Media Proxy 三类不走Authorization头的认证面。结合本文引用的 AuthMiddleware.ts、AdminMiddleware.ts、SudoModeService.ts 与对应测试你可以在接入 Fluxer API 时做到一次写对、无歧义地处理每一种认证结果。赞分享【免费下载链接】fluxerA free and open source instant messaging and VoIP chat app built for friends, groups, and communities.项目地址https://gitcode.com/gh_mirrors/flu/fluxer点击查看免费下载相关推荐LobeChat认证授权JWT令牌验证机制完整指南LobeChat认证授权JWT令牌验证机制完整指南 LobeChat作为一款现代化的开源AI聊天框架其安全认证体系采用了业界标准的JWT令牌验证机制为用户人工智能AI 应用大模型AI Agent多智能体工具调用前端后端SpringReport认证授权JWT令牌管理SpringReport认证授权JWT令牌管理 概述 在企业级报表系统SpringReport中认证授权机制是保障系统安全的核心组件。本文将深入解析Spri企业应用后端前端数据可视化低代码GitHub Actions OIDC令牌终极指南安全认证与授权完全教程GitHub Actions OIDC令牌终极指南安全认证与授权完全教程 GitHub Actions OIDC令牌是现代化CI/CD流水线中的安全认证利器CI/CD开发工具上一篇10 分钟搭好多模态数据标注工作台Label Studio 完整上手指南下一篇Easy Vibe 跨平台实战用 Godot 从零跑通横版、像素与 3D 游戏原型创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
