Skip to content

Runtime identities and configuration

Runtime configuration is reconciled for a named component and read by its declared identity. The accepted secret source, installed broker, filesystem ownership and systemd unit form one access contract. A value’s presence in a checkout or an operator’s shell is not evidence that the running service uses it.

Credentials owns secret classification and replacement. This reference explains how those inputs reach processes and why operator commands must preserve the same identity boundary.

Consumer Input and execution boundary Expected failure behaviour
API service Protected /etc/toolora/api.env, root owner, toolora-secrets group, mode 0640 Missing required reconciliation prevents startup
Installed broker Fixed component policy and accepted secret source, root-owned executable Refuse an unknown component or invalid consumer contract
API operator command dev with supplementary toolora-secrets, restrictive umask Refuse unreadable configuration; do not rerun as root to bypass it
Mail decryption systemd LoadCredential from the declared protected identity file Missing required identity is a component prerequisite failure
Browser build Intended public client configuration only Missing public build inputs fail their validation; secrets never belong in VITE_*
Automated backend tests Cleared provider environment and synthetic local configuration Runtime dotenv files or symlinks are a test-boundary failure

The API unit’s ExecStartPre invokes the installed broker for the API component. The privileged prefix permits that fixed reconciliation; the command is not marked to ignore failure. The API then runs as its declared service identity, with supplementary groups and systemd hardening. Restart=on-failure cannot make invalid configuration acceptable.

Mail archive decryption uses LoadCredential=mail-archive-age-identity and the runtime credential-directory path supplied by systemd. This allows the process to locate its credential without rendering the private key into Git, environment examples or documentation. The mail socket group and archive authority remain separate from permission to expose an attachment to a customer.

The dotenv loader disables interpolation so credential characters are not expanded from ambient variables. Component policy distinguishes required, optional, unused and nonsecret settings. Optional absence is valid only where the owning feature supports it; deleting a required value to obtain a quieter health response changes the contract.

Commands that require shared configuration

Section titled “Commands that require shared configuration”

On AX42, commands that need the shared API configuration run the way the service runs: as dev, with the toolora-secrets supplementary group and umask 0077. Use the exact systemd-run invocation in the repository working agreement. Supply the approved command as its argument rather than copying configuration into a temporary shell.

Running such a command as root can create root-owned state under /home/dev. That can prevent the estate’s dev-owned backup process from reading those files. Successful execution as root is therefore not equivalent to correct runtime execution. Correct ownership through the owning procedure rather than broadening file modes or printing the protected file to diagnose access.

Suppose a synthetic canary starts with schedulers deliberately disabled, but the normal service refuses to start after configuration reconciliation. Compare the component’s required input names, configured identity/groups and broker outcome. Do not copy canary settings into the normal runtime to make it green. Health signals explains why their readiness scopes differ.

After an authorized replacement, verify reconciliation, controlled restart and the affected function without logging the value. A file timestamp proves only that a file changed; a running process may still hold earlier values. Browser configuration needs a new browser build. Automated tests use synthetic inputs and do not require secret-provider access. Local preparation and diagnosis retain those separate paths.