Secrets Infisical

Secret injection and the store

Secrets are not in the config. The config holds references; the wrapper resolves them at start. Everything here follows from that, including the failure that looks like a broken feature and is really a missing key name.

Mechanics

The gateway command is wrapped: the wrapper mints a short-lived machine-identity token, exchanges it for the project's secret set, and execs the real process with those values in its environment only. Nothing lands on disk, so:

• Reading the config tells you what is required. Only running the wrapper tells you what is delivered.
• An exec bypassing the wrapper sees no secrets and returns a false "key missing" verdict — which is why ocexec.py hot mode goes through the wrapper by default.
• The identity is per instance, one file, mode 0600, owned by root (fleet.secrets.identity-file-mode). A wrong project or environment binding shows up as short delivery, never as an error.
• Store values are not encrypted at rest — a recorded decision (fleet.secrets.shared-store-plaintext), not something to fix here.

Never a value

Presence, fingerprint (fp:0000aaaa — an obviously synthetic stub; a real one is eight hex digits of a digest), size bucket, key class, expiry date and full key name answer every operational question. The value answers none of them.

• redact.read_env_file / env_names return names and fingerprints, never values.
• redact.structure_only renders a credential document by shape — safe fields verbatim, identifying fields as fingerprints. That is also the token-sink detector: one account fingerprint across several credential directories.
• Files that are never read whole: any env file, the auth-secret tree, auth profiles, credential directories, identity files, logs. Use a filter that structurally cannot return a value.
• When a provider answers unauthorized the value is useless as evidence; presence, fingerprint parity with what is injected, and expiry are the whole answer.

The delivery audit

Two sets, compared by name:

• required — every secret reference in the effective config, plus the names the compose file passes through.
• delivered — the key names the wrapper actually produces inside the container. Names only; count the characters of a value if you need "non-empty", never print it.

required − delivered non-empty is critical: the feature reading that key is dead and nothing logs an error (fleet.secrets.delivery-short). A count far below the siblings' is a wrong project or environment binding (fleet.secrets.wrong-project); a set of almost nothing is a broken identity (fleet.secrets.identity-broken). Compare against secrets.expected_key_count and against the other instances — a fleet of clones makes the outlier obvious.

Restart precondition

compose restart is R2, but on this deployment it carries an R3 precondition: a running instance holds its secrets in memory; a restart re-resolves them. Restarting while a reference no longer resolves converts a working instance into a dead one, and the cause is invisible afterwards.

Run the delivery audit before any restart, show the resolved-name list in PRECHECK, and refuse while required − delivered is non-empty.

Writing a secret

Three leak paths, all closed at once, plus the one this plugin refuses outright.

The plugin prints the operator a line that reads the value with echo disabled, pipes it to the write, and then verifies by fingerprint alone. Overwriting a key whose fingerprint differs is red line secret-overwrite-different-fingerprint — a rotation, not an edit. Writes get zero retries (gate.RETRY_RULES["secret-write"]): a repeat risks a partial write and one more appearance in a process table.

Identity login: capture stdout only

The store CLI writes an update-check banner to stderr. A login that merges the streams glues that banner onto the token, every later call fails, and the error blames the credentials. Capture stdout alone — a token that "works by hand and fails in the script" is almost always this.

Plaintext env files: parity decides, not existence

A plaintext env file inside the state tree is either redundant (every key matches the store by fingerprint) or load-bearing (a key the store does not deliver). They look identical.

Deleting a load-bearing file takes the instance down at the next restart, silently. Classify by fingerprint parity first, close the gap for load-bearing keys, then neutralise the file by moving it to a quarantine path outside every container volume — never rm. Red line delete-plaintext-env, finding fleet.secrets.plaintext-env; six-step procedure with its stop points and canary restart in references/playbook.md.

A leaked value is not fixed by deleting the file

If a token, client id or key ever sat in a file that left the box — a backup, a copy, a paste — the value is compromised, and removing the file removes the evidence rather than the exposure (fleet.secrets.leaked-in-backup, critical, R4). Rotation is mandatory, not advisable. Do not let the easy action stand in for the undone hard one: "removed the file" while the old value still authenticates closes the ticket without closing the exposure.

Common mistakes

• Reading the config and calling it delivery.
• Running exec without the wrapper and concluding the key is missing.
• Restarting before the delivery precheck.
• Printing a value "just once" to compare it — compare fingerprints.
• Deleting a plaintext env file because the store also has those keys, without checking every key.
• Merging stderr into the login capture.
• Treating a leak as filed once the file is gone.

Procedures: references/playbook.md. Symptom to cause to check: references/troubleshooting.md. Repairs go through /openclaw-ops:repair <selector> --issue <finding-id>.