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.
Identity and configuration reference
Section titled “Identity and configuration reference”| 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 |
Startup and service credentials
Section titled “Startup and service credentials”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.
Synthetic diagnosis and verification
Section titled “Synthetic diagnosis and verification”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.