Secrets and the override policy

Nuvolos provides three layers of secret storage - account, space, and organisation - for handling credentials, API tokens, and other sensitive values. All three are encrypted at rest and only made available inside running Applications. Once the Application stops, the secret is no longer accessible in plain text.

Secrets follow an override policy: more specific scopes win over broader ones.

• Account secrets override Space secrets.

• Space secrets override organisation secrets.

This composition is the point. An organisation manager can set institutional defaults (a database hostname, an API endpoint) at the organisation level. A space administrator can override those defaults for a particular project - for example, pointing at a development database. An individual user can override either with their personal credentials. Each layer specialises further, and Applications always see the most specific value available.

Secrets are preferred over the HOME folder for sensitive information. The HOME area is also encrypted at rest, but it is local to a single Instance and carries some risk of unintended exposure - through distribution to another Instance, or through the HOME area being assigned to a special "shared" user when an Application runs in shared mode. Nuvolos secrets avoid this risk entirely: they are scoped to the user account regardless of which Instance the Application is running in, and shared mode does not propagate them.

Inside a running Application, secrets are exposed as environment variables and as files under /secrets (one file per secret, filename equals secret name, content equals value). This means subprocesses can read them by reading a file, which is sometimes more convenient than environment-variable inheritance.