findscripter Varlock 环境变量防护：会话中密钥零泄露管理
用 Varlock（
@dmno/varlock）给环境变量加一层 schema + 自动脱敏，确保 API key、口令、token 在 AI Agent/Claude 会话、终端回显、日志和 git 提交里默认不出现明文。
何时使用
适用场景：
- 在 Claude/Agent 会话或自动化脚本中需要读取含密钥的
.env，但绝不能让明文密钥进入对话、终端回显或日志。 - 想给项目 env 加「合同」：哪些变量必填、类型是什么、哪些算敏感（默认脱敏），并在启动/CI 期校验。
- 团队希望把 env 加密后随仓库提交（避免「.env 不在版本库、新人永远缺值」），同时保证明文不落库。
- 排查「生产缺变量 / 变量类型错」类故障，需要 fail-fast 的 env 校验。
不该用（负边界）：
- 不替代生产级集中密钥库（HashiCorp Vault / AWS Secrets Manager / 动态短期凭据 / HA / 灾备）——那是
secrets-management/secrets-manager的范围。Varlock 管的是「本地 + 运行时的 env 注入与脱敏」这一段。 - 不是密钥泄露事后扫描器（git 历史扫密钥、轮换应急）——见
env-secrets-hygiene。 - 脱敏是纵深防御的一层，不是绝对保证：自写代码若直接打印
process.env.X仍可能漏，须配合习惯约束。
步骤
- 安装并初始化 schema：用
varlock把现有.env升级为带类型/敏感标注的.env.schema。 - 声明敏感与必填：在 schema 顶部用
@defaultSensitive=true让所有值默认脱敏；逐项用@type、@required、@sensitive=false（明确非敏感项如端口）覆盖。 - 校验：
varlock load（或 CI 里varlock load --fail-fast）确认所有必填项存在、类型合法，缺失即报错退出。 - 运行时注入：用
varlock run -- <你的命令>启动应用/脚本，让 Varlock 注入 env 并接管 stdout/stderr 做实时脱敏，而不是export后裸跑。 - 会话/日志安全：调试时不要
echo $SECRET或print(process.env.SECRET)；要看值用varlock load的脱敏视图（显示为re***ed）。 - 加密提交（可选）：对需要随仓库分发的值用 Varlock 的加密能力，提交密文、
.env.schema入库，明文.env仍.gitignore。
指令
安装与初始化：
# 安装 CLI（也可 npx 直接用）
npm install -g @dmno/varlock
# 或：npx varlock --help
# 把现有 .env 升级成带标注的 .env.schema（交互式扫描你的 .env）
varlock init
.env.schema 示例（@decorator 是 Varlock 的核心约束语法）：
# @defaultSensitive=true # 全局：所有值默认脱敏
# @defaultRequired=false
# ---
# @type=number @sensitive=false @required # 端口非敏感、必填、须为数字
PORT=3000
# @type=url @required
DATABASE_URL=
# @type=string @required @sensitive # 敏感，默认脱敏（@defaultSensitive 已覆盖，可显式标注）
OPENAI_API_KEY=
# @type=email
ADMIN_EMAIL=
校验与运行：
# 加载并校验（缺必填 / 类型不符 → 非零退出，适合放 CI）
varlock load
# 仅看脱敏后的解析结果（敏感值显示为 re***ed，可安全粘进会话/日志）
varlock load --format pretty
# 用 Varlock 注入 env 并启动应用：stdout/stderr 中泄露的密钥会被实时脱敏
varlock run -- node server.js
varlock run -- npm run dev
代码内使用（Node SDK，库会自动避免把敏感值序列化进日志）：
import { load } from 'varlock';
const env = load(); // 经 schema 校验
fetch(api, { headers: { Authorization: `Bearer ${env.OPENAI_API_KEY}` } });
// 不要 console.log(env.OPENAI_API_KEY)；用 varlock run 包裹进程以兜底脱敏
示例
让 Agent 安全地排查「为什么连不上数据库」而不泄露口令：
# ❌ 危险：明文进终端/会话/日志
echo $DATABASE_URL
# ✅ 安全：脱敏视图，确认变量存在且类型对，值显示为 re***ed
varlock load --format pretty | grep DATABASE_URL
# ✅ 安全：在脱敏包裹下实际启动，连接失败的报错里密钥也不会裸露
varlock run -- node scripts/db-ping.js
CI 门禁（缺变量直接红灯）：
# .github/workflows/ci.yml 片段
- name: Validate env schema
run: npx varlock load --fail-fast # 任一必填缺失/类型错即失败
注意事项
- 脱敏是兜底不是免责：自己
console.log/print一个敏感值、或把它拼进 URL 后打印，仍会泄露。养成「只用varlock load脱敏视图看值、用varlock run包裹进程」的习惯。 - 明文
.env始终.gitignore；入库的应是.env.schema（结构契约，不含真实值）与（如使用加密）密文，绝不是明文。 .env.schema里的占位/示例值不要写真实凭据；@example仅作文档。- Varlock 管「本地与运行时注入」这一段，生产真源应是密钥库（Vault / 云 Secret Manager），由 CI/部署阶段注入，而非把生产密钥放进随仓库分发的文件。
- 类型/必填校验能挡「拼写错变量名、忘填、传错类型」，但不校验值的业务正确性（key 是否真有效需运行时验证）。
- 给 Agent 的硬规则：任何情况下不得在回复、命令回显或写入文件中输出未脱敏的密钥；需要值时一律走 Varlock 脱敏通道。
互见
- related：
env-secrets-hygiene—— 互补：本技能做「事前防泄露 + 校验」，它做「事后泄露扫描 + 凭据轮换应急」。 - related：
insecure-defaults-detector—— 检测含 env/密钥在内的不安全默认配置。 - combines_with：
secrets-management—— 生产侧把真源放进 Vault / 云 Secret Manager，Varlock 负责本地与运行时注入这一段。 - combines_with：
secrets-manager—— 集中密钥库的存取/轮换，与 Varlock 的运行时脱敏组合成端到端方案。 - related：
dependency-auditor—— 配套审计依赖供应链风险。
采编自 sickn33/antigravity-awesome-skills（MIT 许可）；原技能源 wrsmith108/varlock-claude-skill，工具 Varlock = @dmno/varlock。