URL Signature Presigner

Presigned URL generator, signer, and secure link API. Create cryptographically signed URLs for temporary downloads, uploads, callbacks, and CDN content. HMAC-SHA256, IP restrictions, method binding. Stateless, no database required.

原始信息汇总

URL Signature Presigner API 数据集概述

基本描述

URL Signature Presigner API 使团队能够使用加密签名的 URL 安全地授予对 URL（下载、上传、重定向、回调）的临时访问权限，无需数据库、会话或持久状态。所有授权逻辑都编码在 URL 签名本身中。验证是完全确定性和无状态的。

核心功能

• 无状态与安全：无需数据库或会话；授权编码在 URL 签名中。
• 供应商无关：适用于任何 CDN、边缘工作程序或服务器；无供应商锁定。
• 确定性验证：相同的输入产生相同的输出；完全可调试。
• 生产就绪：速度足以满足边缘使用；时序安全比较；处理时钟偏差。
• 灵活约束：可按时间、HTTP 方法、IP 地址、请求头或有效负载大小进行限制。
• 加密安全：HMAC-SHA256/SHA512 签名；防篡改 URL。

主要用途

给定一个 URL 和访问约束，此 API 生成一个加密签名的 URL，该 URL：

• 编码过期时间：URL 在过期后自动失效。
• 绑定到 HTTP 方法：限制为 GET、POST、PUT、DELETE 等。
• 按 IP 地址限制：仅允许特定 IP 或 CIDR 范围。
• 需要请求头：强制执行 Content-Type、Authorization 或自定义请求头。
• 限制有效负载大小：防止过大的请求。
• 包含自定义元数据：为您的用例嵌入不透明的、已签名的元数据。

目标用户

• 后端工程师：为文件下载、上传和临时访问生成安全的预签名 URL，无需构建自定义加密逻辑。
• 平台/基础设施团队：跨服务标准化 URL 签名。确保一致、安全的临时访问模式。
• 边缘/CDN 开发人员：在边缘验证预签名 URL，无需数据库查询。非常适合 Cloudflare Workers、AWS Lambda@Edge 和类似平台。
• SaaS 团队：公开临时下载链接、安全的上传 URL 和一次性报告访问，无需维护会话状态。
• API 提供商：发出具有有限有效性的回调 URL 和 Webhook 端点。按时间、方法和来源控制访问。

应用场景

• 临时文件下载：生成自动过期的安全下载链接。
• 安全上传 URL：允许直接上传到存储，并具有大小和时间限制。
• 一次性报告访问：生成仅限特定时间窗口访问的敏感报告链接。
• 具有有限有效性的回调 URL：发出仅在特定时间窗口内有效的 Webhook 回调 URL。
• CDN 支持的受保护内容：通过 CDN 提供受保护内容，无需源站身份验证。
• API 网关临时访问：授予编码在 URL 中的临时 API 访问令牌。
• 预签名 URL：为 S3、云存储和类似服务生成预签名 URL。
• 无状态身份验证：无需数据库即可实现无状态访问控制。

端点

• 签名 URL
  • 方法：POST
  • 路径：/sign
  • 描述：生成具有嵌入式访问约束的加密签名 URL。
• 验证签名 URL
  • 方法：POST
  • 路径：/verify
  • 描述：验证签名 URL 是否有效并解释原因。

请求参数

签名 URL 请求

参数	类型	必需	描述
url	string	是	要签名的基本 URL（完整 URL 或路径）
expiration	number/string	否*	作为 Unix 时间戳（数字）或 ISO 8601 字符串的过期时间
expires_in_seconds	number	否*	从现在开始的生存时间（TTL），单位为秒（expiration 的替代方案）
secret	string	是	签名密钥（原始或编码）
method	string/array	否	允许的 HTTP 方法（GET、POST、PUT、DELETE 等）
allowedIps	string/array	否	允许的 IP 地址或 CIDR 范围
requiredHeaders	object	否	必需的请求头（例如，{"Content-Type": "application/json"}）
maxPayloadSize	number	否	最大有效负载大小（字节）
metadata	object	否	自定义元数据（不透明，已签名但不被解释）
clockSkewTolerance	number	否	时钟偏差容差（秒）（默认值：300）
algorithm	string	否	签名算法：sha256（默认值）或 sha512

• expiration 或 expires_in_seconds 中必须提供一个（但不能同时提供）。

验证 URL 请求

参数	类型	必需	描述
signedUrl	string	是	要验证的签名 URL
secret	string	是	签名密钥（或密钥引用）
method	string	否	正在使用的 HTTP 方法
clientIp	string	否	客户端 IP 地址
headers	object	否	请求头
payloadSize	number	否	有效负载大小（字节）
verificationTime	number	否	Unix 时间戳覆盖（用于测试）
expectedConstraints	object	否	预期约束（可选交叉检查）

安全特性

• 密钥从不记录或返回：密钥仅用于签名/验证。
• 时序安全比较：使用恒定时间比较来防止时序攻击。
• 确定性规范化：URL 解析和规范化是明确的。
• 签名算法版本控制：算法是显式的且具有版本控制，以便未来兼容。
• 时钟偏差容差：处理签名者和验证者之间的时钟差异。
• 防篡改签名：对 URL 的任何修改都会使签名失效。

设计原则

• 完全无状态：无数据库、会话或持久存储。
• 确定性：相同的输入产生相同的输出。
• 供应商无关：适用于任何 CDN、网关或服务器。
• 快速：针对边缘使用进行了优化（<50ms 目标）。
• 可调试：详细的失败原因和每项检查结果。
• 生产就绪：处理边缘情况、时钟偏差和重放风险。

非目标

此 API 不：

• 托管或提供文件
• 充当 CDN 或代理
• 存储或跟踪已发出的 URL
• 提供长期身份验证或身份管理
• 强制执行超出编码约束的使用限制

搜集汇总

背景与挑战

背景概述

这是一个用于生成预签名URL的工具，它通过HMAC-SHA256加密支持临时下载、上传、回调和CDN内容，并具备IP限制和方法绑定功能，无需数据库即可无状态运行。