home / skills / basher83 / lunar-claude / devtools-secrets

devtools-secrets skill

This skill helps you configure and manage secrets with mise, fnox, and infisical, ensuring secure injection and hygiene across environments.

npx playbooks add skill basher83/lunar-claude --skill devtools-secrets

Review the files below or copy the command above to add this skill to your agents.

Files (4)

SKILL.md

4.6 KB

---
name: devtools-secrets
description: >
  Knowledge and guardrails for the mise + fnox + infisical secrets toolchain.
  Use when the user asks to "configure secrets", "set up fnox", "infisical",
  "mise env", "secrets management", "environment variables for secrets",
  or mentions secret injection, secret providers, or env var hygiene.
---

# DevTools Secrets

Knowledge and guardrails for the **mise + fnox + infisical** secrets toolchain.

## Toolchain Validation

**IMPORTANT: Check tool availability before proceeding with any guidance.**

- mise: !`command -v mise >/dev/null 2>&1 && echo "INSTALLED ($(mise --version 2>/dev/null | head -1))" || echo "MISSING — install with: curl https://mise.run | sh"`
- fnox: !`command -v fnox >/dev/null 2>&1 && echo "INSTALLED ($(fnox --version 2>/dev/null | head -1))" || echo "MISSING — install with: mise use -g fnox"`
- infisical: !`command -v infisical >/dev/null 2>&1 && echo "INSTALLED ($(infisical --version 2>/dev/null | head -1))" || echo "MISSING — install with: mise use -g infisical"`

If any tool above shows **MISSING**, stop and help the user install it before
proceeding. Do not provide configuration guidance for tools that aren't
installed.

## Project Config State

- fnox.toml: !`test -f fnox.toml && echo "YES" || echo "NO (run: fnox init)"`
- .infisical.json: !`test -f .infisical.json && cat .infisical.json || echo "NO (run: infisical init)"`
- mise.toml env section: !`grep -A5 '^\[env\]' mise.toml 2>/dev/null || echo "No env section"`

## System/Global Config

- mise global config: !`test -f ~/.config/mise/config.toml && head -10 ~/.config/mise/config.toml || echo "No global mise config"`
- fnox global config: !`test -f ~/.config/fnox/config.toml && head -10 ~/.config/fnox/config.toml || echo "No global fnox config"`
- infisical logged in: !`infisical user get 2>/dev/null | head -3 || echo "Not logged in or not installed"`

## Tool Roles

| Tool | Role |
|------|------|
| **mise** | Task runner + env manager. Orchestrates dev tooling, runs tasks, manages env vars through plugins. |
| **fnox** | Unified secret interface. Abstracts over multiple secret backends (infisical, age, env files) with a single CLI. |
| **infisical** | Remote secrets backend. Stores, syncs, and injects secrets from a central server. |

These tools complement each other: infisical stores secrets remotely, fnox
provides a unified local interface to them, and mise orchestrates tasks that
consume secrets via fnox.

## Integration Chain

The typical flow:

1. **fnox.toml** defines infisical as a provider with project/environment config
2. **`fnox exec --`** resolves secrets from the provider and injects them as env vars
3. **mise tasks** can wrap `fnox exec` to run commands with secrets injected
4. Alternatively, **mise env plugins** can call fnox directly for auto-injection on `cd`

## Secrets Enforcement

This project enforces secrets hygiene via **always-on hooks** in
`.claude/settings.json` (not scoped to this skill):

- **`block-hardcoded-secrets.py`** — Blocks Edit/Write operations containing
  hardcoded API keys, tokens, passwords, or known secret prefixes (sk-, ghp_,
  AKIA, xox[bpras]-)
- **`block-bare-secret-exports.py`** — Blocks Bash commands that `export`
  secret-like env vars without wrapping in `fnox exec` or `infisical run`

These hooks are always active regardless of whether this skill is loaded.

## Configuration Patterns

Detailed configuration for each tool is in the reference files:

- @references/mise-integration.md — mise env plugins, tasks, fnox integration
- @references/fnox-configuration.md — fnox.toml structure, providers, profiles
- @references/infisical-patterns.md — infisical CLI, scanning, CI/CD

## Gotchas

- **Order matters**: fnox.toml must exist before `fnox exec` works. Run
  `fnox init` if missing.
- **Profile mismatches**: fnox profiles (dev/staging/prod) must match infisical
  environment slugs. A mismatch silently returns empty secrets.
- **`.infisical.json` is safe to commit** — it contains project IDs and
  workspace config, not secrets.
- **`fnox.toml` may contain sensitive paths** — review before committing if
  using age-encrypted file provider.
- **mise env plugins run on `cd`** — if a plugin calls fnox and fnox is
  misconfigured, you get errors on every directory change.
- **infisical auth expires** — `infisical login` tokens have a TTL. CI/CD
  should use `INFISICAL_TOKEN` (service token) instead.
- **Token path scope is explicit** — a service token scoped to `/` cannot
  access secrets in child paths like `/git_actions`. Each path requires its
  own token or use `--recursive` with the CLI directly.

Overview

This skill provides knowledge and practical guardrails for configuring the mise + fnox + infisical secrets toolchain. It helps validate tool availability, inspect project and global configuration state, and guide safe secret injection into runtime environments. Use it to enforce env var hygiene and to avoid common misconfigurations when wiring remote secrets into local tasks.

How this skill works

First, the skill checks that mise, fnox, and infisical are installed and stops if any are missing, offering installation steps. It inspects project files (fnox.toml, .infisical.json, mise.toml env section) and global configs to detect missing or mismatched setup. It explains the integration chain: infisical stores secrets, fnox resolves and injects them as env vars, and mise runs tasks or env plugins that consume those vars. It also surfaces common gotchas and enforcement hooks that block unsafe secret patterns.

When to use it

When you need to configure or validate mise, fnox, or infisical on a machine or CI runner.
When setting up secret injection for local development, CI, or deployment tasks.
When converting hardcoded secrets to a secure provider and enforcing env hygiene.
When debugging empty or missing secrets returned from fnox exec.
When adding mise env plugins or wrapping tasks that require secrets.

Best practices

Always run the tool availability checks first; do not proceed if any tool is missing.
Keep fnox.toml present and aligned with infisical profile/environment slugs to avoid silent empty secrets.
Use fnox exec -- to inject secrets into process env rather than exporting raw secret vars.
Prefer service tokens (INFISICAL_TOKEN) in CI and refresh user auth locally as tokens expire.
Audit fnox.toml and any age-encrypted file paths before committing; .infisical.json may be committed safely.

Example use cases

Wrap a local server start command in mise so it runs under fnox exec and receives secrets at runtime.
Initialize fnox (fnox init) and add an infisical provider to fnox.toml, then test secret resolution with fnox exec -- env.
Configure CI to use an INFISICAL_TOKEN scoped for required paths and avoid interactive login steps.
Troubleshoot missing secrets by verifying profile names match infisical environment slugs and confirming infisical login status.
Add a mise env plugin that invokes fnox for automatic secret injection when cd-ing into a project directory.

FAQ

What if a tool shows as MISSING?

Stop and install that tool first. The skill provides the installation command suggestions and will not proceed with configuration guidance until tools are present.

Can I commit .infisical.json to the repo?

Yes. .infisical.json contains project and workspace IDs but not secrets; it is safe to commit.

Why are secrets sometimes empty when using fnox?

Profile names in fnox.toml must match infisical environment slugs exactly; mismatches return empty secrets silently.