Streams 签名验证器

一个轻量级的 Express 服务器，用于验证Quicknode Streams 的 HMAC-SHA256 签名，并支持 gzip 压缩的请求正文。

Author

Emanuel

查看代码库

前端框架/库：

Express

语言：

JavaScript

构建工具/开发服务器：

Node.js

概述

Quicknode Streams 可以对每次 Webhook 发送都附加一个 HMAC-SHA256 签名，以便您确认请求确实来自Quicknode 在传输过程中未被篡改。此示例应用是一个最简化的Express服务器，它详细演示了如何验证这些签名，包括Streams gzip 压缩正文的特殊情况。

签名是根据以下内容的拼接结果计算得出的： 非重复值 + 时间戳 + 有效载荷 (UTF-8)，以您的流的 安全令牌. 当启用压缩功能时，Streams 未压缩的 JSON 在通过 gzip 压缩进行传输之前，因此验证器必须对解码后的字节而非原始的 gzip 字节运行 HMAC 运算。该应用程序使用 express.raw() 借助 body-parser 内置的 gzip 解压功能，可以正确处理这一情况。

有关签名验证逻辑的详细操作指南，请参阅配套指南：《如何验证Streams 消息》。

技术栈

运行环境：Node.js（>=16）
框架：Express
语言：JavaScript
加密货币: Node.js 内置 加密货币 模块 (HMAC-SHA256)

功能

HMAC-SHA256 验证: 验证 x-qn-signature 将该标头与使用您的 Stream 安全令牌本地计算出的摘要进行比对。
支持 Gzip 正文压缩: 正确处理 Content-Encoding: gzip 通过在解压后的 JSON 上运行 HMAC 来处理请求，而不是在原始字节上。
时序安全的比较: 用途 crypto.timingSafeEqual 以防止在签名比对过程中发生定时攻击。
调试日志：打印非ce、时间戳、有效载荷预览，以及计算出的签名和提供的签名，以辅助本地调试。
可配置端口: 默认值为 9999; 使用 PORT 环境变量。

先决条件

您的计算机上已安装Node.jsv16 或更高版本。
一个已配置至少一个流的 Quicknode 。
Quicknode 您的 Stream 的“设置”选项卡中的安全令牌。
使用 ngrok（或任何隧道工具）将您的本地服务器暴露到互联网上，以便Streams 访问它。

项目结构

streams
├── .env.example    # 环境变量模板
├── .gitignore
├── package.json
├── package-lock.json
└── server.js       # Express 网络钩子接收器和 HMAC 验证器

环境变量

复制 .env.example 到 .env 并设置您的流安全令牌：

QN_STREAM_SECRET=此处填写您的超过32字节的安全令牌

您可以在dashboard.quicknode.streams 上的“流”的“设置”选项卡中找到此令牌。

入门指南

1. 克隆该代码库

git clonestreams
cdstreams

2. 安装依赖项

npm 安装

3. 配置环境变量

cp .env.example .env

打开 .env 并设置 QN_STREAM_SECRET 到您的流的安全令牌中。

4. 启动服务器

npm start简体中文（大陆）

服务器监听在 http://localhost:9999/webhook 默认情况下。若要使用其他端口：

PORT=3000 npm start

5. 使用 ngrok 进行公开访问

Streams 一个可公开访问的 URL 来发送webhooks。在另一个终端中：

ngrok http 9999

复制 HTTPS 转发网址（例如 https://abc123.ngrok.io) 并将其设置为您的 Stream 的 webhook URL，同时使用 /webhook 已追加路径：

https://abc123.ngrok.io/webhook

6. 发送测试有效载荷

保存 webhook URL 后，请在Streams 点击“发送有效载荷”按钮，无需等待实际的链上活动，即可触发一次带签名的测试发送。无论是在创建新流还是编辑现有流时，此操作均可使用。请查看服务器终端中的签名调试输出，以确认请求已被接收并验证。

API 端点

方法	路径	描述
`POST`	`/webhook`	接收并验证Streams 的传递

预期的请求头

页眉	描述
`x-qn-nonce`	签名输入中包含的随机非ce值
`x-qn-timestamp`	签名输入中包含 Unix 时间戳
`x-qn-signature`	用于验证的十六进制编码 HMAC-SHA256 摘要