Documentation
¶
Overview ¶
Package security 提供独立的安全原语：
- DownloadToken: 取件下载令牌（时间窗 HMAC + 恒时比较）
- SSRF: 存储端点 URL 校验（scheme 白名单 + 私网地址策略）
Index ¶
- Variables
- func ContentDispositionAttachment(name string) string
- func GenerateDownloadToken(code string) string
- func GeneratePaidDownloadToken(code string) string
- func SetDownloadTokenSecret(secret string)
- func ValidateEndpointHost(hostPort string) error
- func ValidateEndpointURL(rawURL string) error
- func VerifyDownloadToken(code, token string) bool
- type TokenFlavor
Constants ¶
This section is empty.
Variables ¶
var ErrDownloadToken = errors.New("下载令牌无效或已过期，请重新获取取件信息")
ErrDownloadToken 无效或过期的下载令牌
var ErrEndpointURL = fmt.Errorf("存储端点 URL 不合法")
ErrEndpointURL 存储端点 URL 不合法
Functions ¶
func ContentDispositionAttachment ¶ added in v0.18.0
ContentDispositionAttachment 构造下载 Content-Disposition（RFC 6266 + 5987）：
- 引号/反斜杠/控制字符消毒防头断义；
- 纯 ASCII 名只给 filename=；
- 非 ASCII 名（中文等）补 filename*=UTF-8”<pct-encoded>，且 filename= 改用 纯 ASCII 兜底名——老客户端（Android 9 下载器等）不认 filename*，遇到裸 UTF-8 字节会把整个头丢弃变成 download.bin，兜底名至少保住扩展名与可辨识度。
pct-encoded 按 RFC 5987 attr-char 白名单逐字节编码（PathEscape 会放行 `;`/`,` 等非 attr-char，ext-value 里裸分号会截断头参数，故不复用它）。
func GenerateDownloadToken ¶
GenerateDownloadToken 生成下载令牌 "exp.sig"（普通口径：下载时扣取件次数）。 空密钥（未注入）时返回空串——调用方按"功能未启用"处理。
func GeneratePaidDownloadToken ¶ added in v0.31.9
GeneratePaidDownloadToken 生成「已扣次」下载令牌（匿名取件通道专用）。
背景（2026-10-24 真机实测）：匿名取件 retrieve 自身**扣了取件次数**并记了取件人， 随它下发的 download_url 再走 /share/download 时又扣一次 ⇒ 一次取件扣 2 次、 记 2 个取件人（count 过期样式下对方可用次数直接减半）。而分享域的 8 位码路径是 select(不扣) + download(扣 1) ⇒ 两条通道口径分叉。⇒ 匿名取件签**已扣次**令牌， 下载端见此口味即不再扣次、不再重复记取件人 ⇒ 一次取件 = 扣 1 次 + 记 1 个取件人 （与 API 文档承诺的匿名通道「同扣次数」一致）。
func SetDownloadTokenSecret ¶
func SetDownloadTokenSecret(secret string)
SetDownloadTokenSecret 注入下载令牌签名密钥（应与 jwt_secret 等强的独立随机值）。
func ValidateEndpointHost ¶
ValidateEndpointHost 校验裸主机端点（FTP/SFTP 的 host 字段：host[:port]， 无 scheme 不适用 URL 解析）。策略与 ValidateEndpointURL 一致：IP 字面量直接 判私网；域名解析后逐 IP 复判；allow_private_networks 开启时全放行。
func ValidateEndpointURL ¶
ValidateEndpointURL 校验 s3/webdav 存储端点 URL：
- 仅允许 http/https scheme
- 必须携带 host
- DNS 解析后逐 IP 复判私网策略（防重绑定攻击：解析结果非配置期望网段时拒绝）
allowPrivate 未配置（默认 false）时拒绝环回/私网/链路本地地址。 局域网 MinIO/WebDAV（飞牛 NAS）部署需显式 security.ssrf.allow_private_networks=true。
func VerifyDownloadToken ¶
VerifyDownloadToken 恒时比较校验令牌（exp 窗口 + HMAC 签名）。 **两种口径都算有效**（普通/已扣次）——有效性判定与扣次口径是两件事。
Types ¶
type TokenFlavor ¶ added in v0.31.9
type TokenFlavor int
TokenFlavor 下载令牌的校验结果与**扣次口径**。
const ( // TokenInvalid 令牌无效/过期/签名不符 TokenInvalid TokenFlavor = iota // TokenNormal 普通令牌：签发方**未**扣过取件次数 ⇒ 下载时扣 1 次 // （select 面签发；匿名 download 跳转面签发——Peek 不扣次） TokenNormal // TokenPaid 「已扣次」令牌：签发方**已**扣过取件次数（匿名取件 retrieve 面签发） // ⇒ 下载时**不再**扣次（否则一次取件扣两次，count 样式下对方次数减半） TokenPaid )
func VerifyDownloadTokenFlavor ¶ added in v0.31.9
func VerifyDownloadTokenFlavor(code, token string) TokenFlavor
VerifyDownloadTokenFlavor 校验令牌并返回其扣次口径（恒时比较）。
Source Files