# =============================================
# WhiteList 示例文件 (whitelist.example.txt)
# =============================================
# 本文件演示如何编写白名单条目，供参考。
# 实际使用时复制为一个新文件，例如：
#   cp whitelist.example.txt /etc/rpc_whitelist.txt
# 然后在启动环境中设置：
#   export WHITELIST_FILE=/etc/rpc_whitelist.txt
# =============================================
# 匹配逻辑说明：
# 程序会从 HTTP Header 中读取 Origin 与 Referer，针对其原始值生成多个候选：
#   1) 原始字符串                 (例如 https://sub.example.com:8443/path?a=1)
#   2) scheme://host               (例如 https://sub.example.com:8443)
#   3) host:port                   (例如 sub.example.com:8443)
#   4) host（去掉端口）            (例如 sub.example.com)
# 只要任一候选与白名单条目（精确或通配）命中，即直接放行请求。
# =============================================
# 行规则：
# - 空行忽略
# - 以 # 或 // 开头为注释
# - 包含 '*' 视为通配模式（支持多处出现）
# - 其他视为精确匹配（完全相等才命中）
# =============================================
# 通配模式说明：
# 1) *.example.com          匹配任意子域层级，但不匹配 example.com 本身。
# 2) example.com*           匹配以 example.com 开头的任意字符串（后面可以跟端口、路径、参数等）。
# 3) *example.com           匹配以 example.com 结尾的字符串（前面可以有任意内容）。
# 4) *mid*                  匹配包含 mid 的任意字符串。
# 5) https://*.foo.bar      匹配带有 scheme 的形式，子域 + 域名整体匹配。
# 注意：通配符 '*' 会被转换为正则中的 '.*'，因此可能跨越分隔符（如 : / ?）。请谨慎使用过宽的模式。
# =============================================
# 推荐写法：
# - 想同时允许根域和其子域：显式列出根域 + 通配子域：
#       example.com
#       *.example.com
# - 强调只允许 HTTPS：写 scheme 前缀，而不是仅写 host：
#       https://secure.example.com
# - 避免使用过宽的 *example*，除非确实要开放非常多相似来源。
# =============================================
# 精确匹配示例 --------------------------------------------------
https://example.com
https://example.com:8443
example.com
sub.example.com
sub.example.com:8443
# 如果需要既允许根域又允许所有子域：根域 + 通配（如下）
example.org
*.example.org

# 通配匹配示例 --------------------------------------------------
# 任意层级子域（不含根域本身）
*.service.local
# 允许任意以 api. 开头的 host（含可能的端口、路径）
api.example.net*
# 包含内部标识 internal 的所有来源
*internal*
# 允许以 staging.example.io 结尾的所有字符串
*staging.example.io
# scheme + 子域限制（仅 HTTPS 且必须有子域）
https://*.secure.zone

# 复杂模式示例 --------------------------------------------------
# 允许所有以 https://edge 开头的来源（例如 https://edge1.cdn.com/path）
https://edge*
# 允许所有 host 中包含 corp- 且以 .intra 结尾
*corp-*.intra
# 允许包含 token 参数的来源（可能过宽，谨慎）
*token=*

# 不推荐或需谨慎的模式 ------------------------------------------
# *example*          过于宽泛，可能命中恶意拼接域名，如 badexamplex.com
# *://*              几乎匹配全部，有严重风险
# *                  匹配任意字符串（请勿使用）

# 说明：程序不自动裁剪路径，因此精确匹配含路径的条目也可：
https://example.com/specific/path
# 上面这一行仅当 Origin/Referer 原始值完全包含该路径时才命中。

# 端口处理说明：
# - 如果白名单写了 example.com:3000，则只匹配带该端口的候选。
# - 写 example.com 则同时可匹配 host 形式（不含端口），但不会自动匹配 example.com:3000。

# ===== 最后建议： =====
# 生产环境中尽量使用：明确 host / scheme + host，同时配合专门的子域通配；避免过宽的 *X* 形式。
# 若需进一步控制（只允许特定端口、限制路径范围等），建议在应用层增加额外校验逻辑。
# ==============================================================

