feat(config): Hardening of secret file handling

Author: mpolitzer

compose.individual-services.yaml

@@ -47,7 +47,11 @@ services:
       - devnet
     restart: "no"
     secrets:
-      - database_connection
+      - source: database_connection
+        target: database_connection
+        uid: "102"
+        gid: "102"
+        mode: 0440
     environment:
       <<: *env
 
@@ -64,9 +68,17 @@ services:
     ports:
       - "10001:10001" # Supervisor
     secrets:
-      - auth_mnemonic
+      - source: auth_mnemonic
+        target: auth_mnemonic
+        uid: "102"
+        gid: "102"
+        mode: 0400
       - blockchain_http_endpoint
-      - database_connection
+      - source: database_connection
+        target: database_connection
+        uid: "102"
+        gid: "102"
+        mode: 0440
     environment:
       <<: *env
 
@@ -87,8 +99,16 @@ services:
       - "10002:10002" # Supervisor
       - "10012:10012" # Inspect Service
     secrets:
-      - auth_mnemonic
-      - database_connection
+      - source: auth_mnemonic
+        target: auth_mnemonic
+        uid: "102"
+        gid: "102"
+        mode: 0400
+      - source: database_connection
+        target: database_connection
+        uid: "102"
+        gid: "102"
+        mode: 0440
     environment:
       <<: *env
 
@@ -103,7 +123,11 @@ services:
     ports:
       - "10003:10003" # Supervisor
     secrets:
-      - database_connection
+      - source: database_connection
+        target: database_connection
+        uid: "102"
+        gid: "102"
+        mode: 0440
     environment:
       <<: *env
 
@@ -120,9 +144,17 @@ services:
     ports:
       - "10004:10004" # Supervisor
     secrets:
-      - auth_mnemonic
+      - source: auth_mnemonic
+        target: auth_mnemonic
+        uid: "102"
+        gid: "102"
+        mode: 0400
       - blockchain_http_endpoint
-      - database_connection
+      - source: database_connection
+        target: database_connection
+        uid: "102"
+        gid: "102"
+        mode: 0440
     environment:
       <<: *env
 
@@ -138,9 +170,17 @@ services:
       - "10005:10005" # Supervisor
       - "10011:10011" # Jsonrpc API service
     secrets:
-      - auth_mnemonic
+      - source: auth_mnemonic
+        target: auth_mnemonic
+        uid: "102"
+        gid: "102"
+        mode: 0400
       - blockchain_http_endpoint
-      - database_connection
+      - source: database_connection
+        target: database_connection
+        uid: "102"
+        gid: "102"
+        mode: 0440
     environment:
       <<: *env
 volumes:

compose.yaml

@@ -33,6 +33,12 @@ services:
       interval: 3s
       timeout: 3s
       retries: 5
+    secrets:
+      - source: database_connection
+        target: database_connection
+        uid: "102"
+        gid: "102"
+        mode: 0440
     environment:
       POSTGRES_PASSWORD: password
       POSTGRES_DB: rollupsdb
@@ -46,7 +52,11 @@ services:
     networks:
       - devnet
     secrets:
-      - database_connection
+      - source: database_connection
+        target: database_connection
+        uid: "102"
+        gid: "102"
+        mode: 0440
     restart: "no"
     environment:
       <<: *env
@@ -69,9 +79,17 @@ services:
       - "10011:10011" # Jsonrpc API service
       - "10012:10012" # Inspect Service
     secrets:
-      - auth_mnemonic
+      - source: auth_mnemonic
+        target: auth_mnemonic
+        uid: "102"
+        gid: "102"
+        mode: 0400
       - blockchain_http_endpoint
-      - database_connection
+      - source: database_connection
+        target: database_connection
+        uid: "102"
+        gid: "102"
+        mode: 0440
     environment:
       <<: *env
 

docs/secret-files.md

@@ -0,0 +1,117 @@
+# Secret File Permissions
+
+The node reads several sensitive configuration values from files via the
+`*_FILE` environment variables. To avoid silently accepting insecure secret
+mounts, the node validates the file **type and permissions** before reading
+the contents and rejects files that violate the policy.
+
+This applies to the file-backed variants of:
+
+| Variable                                    | Policy        | Sensitivity                              |
+| ------------------------------------------- | ------------- | ---------------------------------------- |
+| `CARTESI_AUTH_MNEMONIC_FILE`                | strict-secret | signing material (mnemonic)              |
+| `CARTESI_AUTH_PRIVATE_KEY_FILE`             | strict-secret | signing material (private key)           |
+| `CARTESI_BLOCKCHAIN_HTTP_AUTHORIZATION_FILE`| credential    | outbound authorization header            |
+| `CARTESI_DATABASE_CONNECTION_FILE`          | credential    | database connection string (DSN)         |
+| `CARTESI_BLOCKCHAIN_HTTP_ENDPOINT_FILE`     | regular-file  | endpoint without embedded credentials    |
+
+## Policy tiers
+
+### strict-secret (signing material)
+
+Applies to the mnemonic and private-key files.
+
+The file:
+
+- **must be a regular file** (not a directory, device, pipe, etc.);
+- **must not be readable, writable, or executable by group or world**
+  (`mode & 0o077` must be `0`, i.e. owner-only, such as `0400` or `0600`);
+- **must be owned by the current effective user** on POSIX systems.
+
+On violation the node refuses to start. This is a hard failure, not a warning.
+
+### credential (authorization headers, DSNs)
+
+Applies to files carrying passwords or authorization tokens.
+
+The file:
+
+- **must be a regular file**;
+- **must not be world-readable or world-writable**
+  (`mode & 0o007` must be `0`).
+
+Group-readable files are accepted (e.g. `0640`), so a shared group can mount
+credentials when needed.
+
+### regular-file (non-secret endpoint files)
+
+Applies to endpoint files that do not carry credentials.
+
+The file:
+
+- **must be a regular file**.
+
+No permission restrictions beyond that. This tier keeps URL convenience files
+from being conflated with private key material.
+
+## Non-POSIX platforms
+
+On Windows and other platforms that do not expose POSIX mode semantics, only the
+regular-file check is enforced; mode and ownership checks are skipped. Treat
+this as best-effort hardening, not cross-platform parity.
+
+## Required file modes
+
+When mounting secrets into the container, use owner-only permissions for signing
+material:
+
+```sh
+chmod 600 /run/secrets/auth_mnemonic
+chmod 600 /run/secrets/auth_private_key
+```
+
+and group-only or owner-only permissions for credential files:
+
+```sh
+chmod 640 /run/secrets/blockchain_http_authorization
+chmod 640 /run/secrets/database_connection
+```
+
+The node runs as a non-root user (`cartesi`, uid 102, gid 102). Secret files must
+be readable by that user.
+
+## Docker Compose
+
+Docker Compose mounts secrets into `/run/secrets/<name>`. By default they are
+**owned by `root`** and **world-readable (`0444`)**, which the `strict-secret`
+policy rejects. Mount signing secrets with an explicit mode and ownership so
+they are readable only by the node user, for example:
+
+```yaml
+services:
+  node:
+    secrets:
+      - source: auth_mnemonic
+        target: auth_mnemonic
+        uid: "102"
+        gid: "102"
+        mode: 0400
+
+secrets:
+  auth_mnemonic:
+    file: test/secrets/auth_mnemonic.txt
+```
+
+> Note: the `uid`, `gid`, and `mode` fields on service secrets require a recent
+> Docker Compose version. Verify support in your environment; if they are
+> unsupported, mount the secret as a bind volume with the host file owned by uid
+> 102 and mode `0400` instead.
+
+The node rejects insecure secret files at startup with a message such as:
+
+```text
+failed to parse CARTESI_AUTH_MNEMONIC_FILE: file "/run/secrets/auth_mnemonic"
+is accessible by group or others; expected owner-only permissions
+```
+
+Error messages never include the file contents.

internal/config/generate/Config.toml

@@ -184,13 +184,15 @@ used-by = ["evmreader", "claimer", "node", "prt"]
 
 [blockchain.CARTESI_BLOCKCHAIN_HTTP_ENDPOINT]
 file = true
+file-policy = "regular-file"
 go-type = "URL"
 description = """
 HTTP endpoint for the blockchain RPC provider."""
 used-by = ["evmreader", "claimer", "node", "prt"]
 
 [blockchain.CARTESI_BLOCKCHAIN_HTTP_AUTHORIZATION]
 file = true
+file-policy = "credential"
 go-type = "RedactedString"
 description = """
 Additional security when interacting with providers.
@@ -334,6 +336,7 @@ used-by = ["claimer", "node", "cli", "prt"]
 
 [auth.CARTESI_AUTH_PRIVATE_KEY]
 file = true
+file-policy = "strict-secret"
 go-type = "RedactedString"
 description = """
 The node will use this private key to sign transactions."""
@@ -342,6 +345,7 @@ used-by = ["claimer", "node", "cli", "prt"]
 
 [auth.CARTESI_AUTH_MNEMONIC]
 file = true
+file-policy = "strict-secret"
 go-type = "RedactedString"
 description = """
 The node will use the private key generated from this mnemonic to sign transactions."""
@@ -382,6 +386,7 @@ used-by = ["claimer", "node", "cli", "prt"]
 [database.CARTESI_DATABASE_CONNECTION]
 default = ""
 file = true
+file-policy = "credential"
 go-type = "URL"
 description = """
 Postgres endpoint in the 'postgres://user:password@hostname:port/database' format (URL).

internal/config/generate/code.go

@@ -52,6 +52,20 @@ var funcMap = template.FuncMap{
 		// For example, "int" becomes "toInt", "Duration" becomes "toDuration".
 		return "to" + strings.ToUpper(goType[:1]) + goType[1:]
 	},
+	// toFilePolicyConst maps a Config.toml file-policy value to the
+	// corresponding SecretFilePolicy constant name emitted in generated code.
+	"toFilePolicyConst": func(policy string) string {
+		switch policy {
+		case filePolicyStrict:
+			return "SecretFilePolicyStrict"
+		case filePolicyCredential:
+			return "SecretFilePolicyCredential"
+		case "", filePolicyRegular:
+			return "SecretFilePolicyRegularFileOnly"
+		default:
+			panic("invalid file-policy: " + policy)
+		}
+	},
 	// splitLines splits a string into lines (by "\n").
 	"splitLines": func(s string) []string {
 		return strings.Split(s, "\n")
@@ -122,7 +136,6 @@ package config
 
 import (
 	"fmt"
-	"os"
 	"strings"
 
 	"github.com/spf13/viper"
@@ -221,7 +234,7 @@ func Get{{ toFieldName .Name }}() ({{ .GoType }}, error) {
 	{{- if .File }}
 	if s == "" {
 		filename := viper.GetString({{toConstName .Name}}_FILE)
-		contents, err := os.ReadFile(filename)
+		contents, err := ReadConfigFileWithPolicy(filename, {{ toFilePolicyConst .FilePolicy }})
 		if err != nil {
 			return notDefined{{ .GoType }}(), fmt.Errorf("failed to parse %s: %w", {{ toConstName .Name }}_FILE, err)
 		}

internal/config/generate/docs.go

@@ -25,6 +25,18 @@ func generateDocsFile(path string, env []Env) {
 		"quote": func(s string) string {
 			return `"` + s + `"`
 		},
+		"filePolicyDesc": func(p string) string {
+			switch p {
+			case filePolicyStrict:
+				return "strict-secret (owner-only regular file; rejects group/world access)"
+			case filePolicyCredential:
+				return "credential (regular file; rejects world access)"
+			case "", filePolicyRegular:
+				return "regular-file (must be a regular file)"
+			default:
+				return p
+			}
+		},
 	}
 	tmpl := template.Must(template.New("docs").Funcs(funcMap).Parse(docsTemplate))
 
@@ -56,6 +68,9 @@ This file documents the configuration options.
 {{.Description}}
 
 * **Type:** {{backtick .GoType}}
+{{- if .File}}
+* **File policy:** {{filePolicyDesc .FilePolicy}}
+{{- end}}
 {{- if .Default}}
 * **Default:** {{.Default | quote | backtick}}
 {{- end}}