Schema crate

Registry data types live in a separate, dependency-light crate so data repositories can decode them without the engine:

[dependencies]
secret-manager-schema = { package = "caniko-secret-manager-schema", version = "0.4.7" }

secret_manager_schema::accounts::AccountCatalogue decodes switchable service accounts: several accounts per credential service, a fleet default, and per-host and per-user overrides. select(service, host, user) returns the host override, else the user override, else the default; validate checks that every default and override names a registered account. The matching Pkl classes (Account, AccountService, AccountHost, AccountCatalogue) are in pkl/SecretRegistry.pkl.

Library API

The secret_manager library provides the building blocks used by the CLI.

The registry package is caniko-secret-manager. Use a Cargo package alias to retain the existing library imports:

[dependencies]
secret-manager = { package = "caniko-secret-manager", version = "0.4.0" }

The minimum supported Rust compiler is 1.88. Public Forgejo authentication types now use Forgejo API 0.11; callers exchanging those types must use the same generation. The Reqwest 0.13 blocking client retains JSON, Rustls, HTTP/2, charset decoding and system proxy discovery. Persisted version-1 sync-state records retain their destination identities across the TOML 1.1 migration, including GitHub environment ownership.

Modules

Core types

Store

pub struct Store {
    pub root: PathBuf,
}

Methods:

• Store::current_dir() — root at cwd
• Store::discover() — from $SECRET_MANAGER_STORE or nearest flake.nix
• store.master_identities() — sorted age/master-*.pub / age/master_*.pub stubs
• store.resolve_identities(flags) — flags → SECRET_MANAGER_AGE_IDENTITIES → stubs

TargetSpec

pub enum TargetSpec {
    Home(HomeTarget),
    SharedHome(SharedHomeTarget),
    System(SystemTarget),
    Forgejo(ForgejoTarget),
}

Each variant encodes the source expression, secret path, module path, and delivery targets.

RenderedModule

The output of rendering a target spec into a Nix module file:

pub struct RenderedModule {
    pub path: PathBuf,       // Module file path relative to store root
    pub body: String,        // Nix module content
    pub default_nix: PathBuf, // Parent default.nix for import splicing
    pub secret_path: PathBuf, // .age file path relative to store root
    pub stack: Stack,
}

StoreEnv trait

pub trait StoreEnv {
    fn validate_host(&self, host: &str) -> Result<()>;
    fn resolve_home_user(&self) -> Result<String>;
}

• LocalEnv — permissive implementation for standalone use
• TestEnv — test implementation (resolves user to "can")

Key functions

render_modules

pub fn render_modules(
    targets: &[TargetSpec],
    generator: Option<&GeneratorSpec>,
) -> Vec<RenderedModule>

Renders a set of targets into Nix modules by calling mkSecret with the appropriate source expressions and delivery targets.

render_body

pub fn render_body(target: &TargetSpec, generator: Option<&GeneratorSpec>) -> String

Renders a single target into the body of a Nix module.

run_plan

pub fn run_plan(args: &CommonSourceArgs, plan: AddPlan) -> Result<()>

Executes an AddPlan: validates destinations, prepares secret sources, writes modules, runs generation or encryption, stages, and rekegs.

camel

pub fn camel(s: &str) -> String

Converts kebab-case and snake_case to CamelCase used for age name derivation.

Example: "nix-trusted" → "NixTrusted", "copr-token" → "CoprToken".

default_forgejo_age_name

pub fn default_forgejo_age_name(instance: &str, slug: &str) -> String

Derives the default agenix secret name for a Forgejo credential.

Example: ("codeberg", "copr-token") → "forgejoRunnerCodebergCoprToken"

default_forgejo_ssh_key_age_name

pub fn default_forgejo_ssh_key_age_name(slug: &str) -> String

Derives the default agenix secret name for a Forgejo SSH key.

Example: "aur-ssh-key" → "forgejoActionsAurSshKey"