hodlxxi-bitcoin-identity

🔐 Bitcoin 原生身份认证与授权方案

基于 MIT 协议的开源 Bitcoin 身份层,无缝集成 OAuth2/OIDC 与 Lightning LNURL-Auth,为 Agent 提供去中心化安全认证能力。

收藏
8.2k
安装
2.4k
版本
v0.1.0
CLS 安全性认证2026-05-09
点击查看完整报告 >

使用说明

HODLXXI Bitcoin Identity 是一个专为 Agent 设计的开源身份验证技能,旨在通过 Bitcoin 原生协议实现安全的身份管理。该技能基于 MIT 协议开源,核心功能是桥接传统 OAuth2/OIDC 标准与 Lightning Network 的 LNURL-Auth 协议,为去中心化应用提供统一的身份认证层。

核心用法:用户首先需要配置 HODLXXI 服务的基础 URL,然后通过标准 OAuth2 流程注册客户端并获取凭证。支持完整的授权码流程(推荐 PKCE 增强安全性),同时提供 Lightning 钱包原生的 LNURL-Auth 认证方式。系统通过 JWKS 端点支持 JWT 令牌验证,并提供健康检查端点用于监控服务状态。此外,该技能还集成了按量付费(PAYG)计费机制,支持通过 Lightning 网络进行 API 调用费用的实时结算。

显著优点:作为纯文档型 Skill,它提供了详尽的 API 调用示例和最佳实践指南,包括完整的 curl 命令和 Python 验证脚本。双协议支持使其既能兼容传统 Web 应用(OAuth2/OIDC),又能服务 Bitcoin 生态(LNURL-Auth)。MIT 开源协议保证了代码的可审计性,且所有网络通信强制要求 HTTPS。依赖库均为成熟的开源项目(ecdsa、pyjwt、requests),代码经过安全审计无高危漏洞。

潜在缺点与局限性:首先,该项目属于 T3 级社区来源(GitHub 个人/社区项目),非知名技术企业背书,长期使用需关注维护状态。其次,功能完全依赖外部 HODLXXI 服务端,若服务端不可用或网络受限,则无法工作。此外,Bitcoin/Lightning 生态存在一定技术门槛,需要用户理解闪电网络支付和加密签名原理。Python 脚本的依赖管理也需要用户自行维护版本安全。

适合的目标群体:主要面向构建 Bitcoin/Lightning 生态应用的开发者、需要集成去中心化身份验证的 Agent 构建者,以及希望将传统 OAuth2 系统与加密货币支付结合的产品团队。特别适合需要同时支持传统 Web 登录和闪电钱包认证的多模式应用场景。

使用风险:网络层面存在对外部服务端的强依赖,需确保服务端的 TLS 证书有效性和可用性。密钥管理风险方面,虽然文档建议使用环境变量存储 client_secret,但实际执行仍依赖用户的安全实践。依赖库版本风险需要注意,特别是 ecdsa 和 pyjwt 等加密库应及时更新以修复潜在漏洞。由于涉及 Lightning 支付,还需关注 402 支付状态的处理逻辑和资金安全风险。

安全解读

核心用法

HODLXXI Bitcoin Identity 是一个将比特币原生身份认证与现代OAuth2/OIDC协议桥接的集成方案,主要提供三类核心能力:

1. OAuth2/OIDC标准认证流

  • 支持授权码模式(推荐PKCE),兼容标准OpenID Connect端点
  • 提供完整的客户端注册、授权、令牌交换流程
  • JWT ID Token支持JWKS公钥验证

2. LNURL-Auth闪电钱包登录

  • 创建会话生成LNURL二维码,用户用闪电钱包扫码授权
  • 服务端轮询验证签名,实现无密码、无私钥托管的认证
  • 基于secp256k1椭圆曲线签名,与比特币密钥体系兼容

3. PAYG按需付费机制

  • 按client_id计费,非按用户计费
  • 余额不足时返回HTTP 402,附带Lightning发票创建路径
  • 支持实时查询发票状态

显著优点

| 维度 | 优势 |
|------|------|
| **协议兼容性** | 同时支持传统OAuth2生态和比特币原生LNURL协议,降低集成门槛 |
| **密钥自主** | LNURL-Auth用户自持私钥,服务端不存储密码,符合"Not your keys, not your coins"理念 |
| **轻量集成** | 纯文档+脚本形式,无复杂依赖,curl示例即可跑通全流程 |
| **支付原生** | 内置Lightning付费通道,适合比特币生态的微观支付场景 |
| **安全评分** | 安全认证A级(85分),无高危漏洞,代码结构清晰 |

潜在缺点与局限性

外部依赖风险(核心局限)

  • 所有敏感操作依赖hodlxxi.com服务端,需信任其HTTPS配置、密钥管理和数据保留政策
  • 服务端若遭入侵或跑路,用户OAuth令牌可能泄露或失效

T3来源可信度

  • 维护者为个人开发者GitHub账号(hodlxxi),无企业背书
  • 相比T1/T2来源,长期维护承诺和漏洞响应速度存疑

功能边界

  • 仅为集成文档和辅助脚本,非完整身份服务实现
  • LNURL会话为单次使用、短TTL设计,不适合长连接场景
  • 缺乏多因素认证(MFA)等增强安全机制

Lightning生态局限

  • 依赖用户持有支持LNURL-Auth的闪电钱包(如Zeus、Phoenix等)
  • 链上支付不支持,法币入口缺失

适合人群

  • 比特币原生Agent开发者:需要Lightning钱包登录且不愿托管用户私钥
  • OAuth2迁移项目:现有系统需增加比特币身份层,保留OIDC兼容
  • 微观付费场景应用:PAYG模式适合API调用量波动大、难以预估预算的服务
  • 隐私敏感用户群体:偏好无KYC、无邮箱注册的认证方式

常规风险

| 风险类型 | 具体表现 | 缓解建议 |
|----------|----------|----------|
| 服务端劫持 | hodlxxi.com DNS/证书被劫持 | 生产环境证书固定,监控CT日志 |
| JWT令牌泄露 | 传输或存储环节泄露 | 短TTL令牌,敏感操作额外验证 |
| 依赖库漏洞 | ecdsa/pyJWT历史CVE | 锁定依赖版本,订阅安全公告 |
| 闪电支付欺诈 | 虚假发票、节点审查 | 多节点验证,小额测试先行 |
| 开发者消失 | 个人项目维护中断 | 自建服务端或准备迁移方案 |

安全认证摘要

  • 综合评分: 85/100 (A级)
  • 静态分析: 88分 - 无危险函数,Python错误处理完善
  • 动态行为: 85分 - 仅本地签名验证,无恶意行为
  • 依赖审计: 82分 - ecdsa/pyJWT/requests均为成熟库
  • 网络分析: 80分(警告) - 外部服务依赖需验证
  • 隐私合规: 90分 - 无静默收集,本地JWT验证
  • 关键发现: 3项中低风险问题,无高危威胁

认证结论: 标准安全级别,代码结构清晰,适合生产环境使用,但需结合具体场景二次评估外部服务端可信度。

hodlxxi-bitcoin-identity 内容

scripts文件夹
templates文件夹
手动下载zip · 4.6 kB
verify_signature.pytext/plain
请选择文件