From 4bb186c83ec74f1d95f4cdfbc1824b4256107507 Mon Sep 17 00:00:00 2001 From: Tanja Ulianova Date: Wed, 22 Jul 2026 17:35:26 +0200 Subject: [PATCH] docs: add declarative manifest-plugins section to secrets management Documents the upcoming [plugins] manifest section as an experimental, declarative alternative to hand-written on-activate retrieval hooks, using the in-development 1Password plugin as the example. Based on the Forge secrets-management effort (ADR-001 reference-only JIT, ADR-002 generic plugin system) and the manifest-plugins-prototype branch. Co-Authored-By: Claude Fable 5 --- concepts/secrets-management.mdx | 57 +++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/concepts/secrets-management.mdx b/concepts/secrets-management.mdx index bd4974e..e9cacf1 100644 --- a/concepts/secrets-management.mdx +++ b/concepts/secrets-management.mdx @@ -163,6 +163,63 @@ They never touch disk. to add the required packages to your environment. + +## Declarative secrets with manifest plugins + + + Manifest plugins are **experimental** and under active development. + The `[plugins]` section is not yet part of a stable manifest schema + version, and Flox versions without the feature reject a manifest + containing it with an "unknown field" error. + Details described here may change before release. + + +The hook examples above hand-write the retrieval command for each secret. +Flox is adding a declarative alternative: install a secrets plugin +package and declare *which* secrets your environment needs in a +`[plugins]` section of the manifest. +The plugin performs the retrieval for you at activation. + +The model is the same reference-only JIT pattern: the manifest carries +each secret's *location* in the store, never its value, so it remains +safe to commit. + +For example, with the 1Password plugin (currently in development): + +```toml +[install] +1password.pkg-path = "flox/1password" + +[plugins.1password] +GH_TOKEN = "op://Private/GitHub Work Token/credential" +PGPASSWORD = "op://Private/Postgres/password" +``` + +Installing `flox/1password` provides the `op` CLI together with its Flox +plugin. +On `flox activate`, the plugin resolves each +`op://vault/item/field` reference against your active 1Password session +and exports the value as the named environment variable. + +Key behavior: + +- Plugin data lives under `[plugins.]`, keyed by the plugin's + package name. + Each plugin defines and documents the shape of its own table; for + secrets plugins the convention is a flat table of + `ENV_VAR = "path/to/secret"`. +- Retrieval runs during activation **before** the `on-activate` hook, + so hooks and `[services]` can use the variables. +- Plugins run in the `dev` and `build` activation modes, but not in + `run` mode (`flox activate --mode run`). +- Primary auth still belongs to the secret store—for example an active + `op` session or biometric unlock—exactly as in phase 1 of the JIT + pattern above, and the security properties listed above apply + unchanged. + +The manual hook pattern keeps working and remains the way to integrate +a secret store that doesn't have a plugin. + ## Rotating a secret Because the value lives in the store, not the manifest, rotation requires