feat(config): add agent_user and jenkins_home config options

charmcraft.yaml

@@ -61,6 +61,20 @@ config:
       description: |
         Comma-separated list of labels to be assigned to the agent in Jenkins. If not set it will
         default to the agents hardware identifier, e.g.: 'x86_64'
+    agent_user:
+      type: string
+      default: jenkins
+      description: |
+        OS user that runs the Jenkins agent systemd service. Defaults to jenkins.
+        The charm ensures the user exists, owns JENKINS_HOME, and is granted
+        passwordless sudo. Note that the systemd unit file itself is always owned
+        by root.
+    jenkins_home:
+      type: string
+      default: /var/lib/jenkins
+      description: |
+        Home directory for the Jenkins agent, passed to the agent as -workDir and
+        used as the working directory by the systemd service.
     websocket_mode:
       type: boolean
       default: true

docs/changelog.md

@@ -6,6 +6,18 @@
 
 Each revision is versioned by the date of the revision.
 
+## August 12, 2026
+
+- Harden configurable agent user and home directory handling with validated paths,
+  least-privilege ownership, and fail-fast account setup.
+- Keep password-free privileged access provisioning deterministic and fail closed
+  when validation or installation fails.
+- Render systemd environment values with systemd escaping instead of HTML
+  escaping, reject line-breaking control characters, and avoid logging secrets.
+- Fail installation when the agent account, home directory, package setup, or
+  privileged-rule validation cannot be completed; only the configured home
+  directory itself is re-owned.
+
 ## 2026-07-06
 
 - Add `-websocket` flag to agent connection to support HTTP-only reverse proxies (traefik-k8s ingress).

pyproject.toml

@@ -63,6 +63,7 @@ integration = [
   "protobuf==7.35.1",
   "pytest",
   "pytest-operator",
+  "tenacity",
 ]
 
 [tool.uv]

src/charm_state.py

@@ -5,8 +5,10 @@
 
 import logging
 import os
+import re
 import typing
 from dataclasses import dataclass
+from pathlib import Path
 
 import ops
 from dotenv import dotenv_values
@@ -17,6 +19,8 @@
 AGENT_RELATION = "agent"
 
 logger = logging.getLogger()
+_AGENT_USER_PATTERN = re.compile(r"^[a-z_][a-z0-9_-]{0,31}\$?$")
+_JENKINS_HOME_PATTERN = re.compile(r"^/[A-Za-z0-9._/-]+$")
 
 
 class Credentials(BaseModel):
@@ -132,6 +136,8 @@ class State:
     unit_data: UnitData
     websocket_mode: bool
     jenkins_agent_service_name: str = "jenkins-agent"
+    agent_user: str = "jenkins"
+    jenkins_home: Path = Path("/var/lib/jenkins")
 
     @classmethod
     def from_charm(cls, charm: ops.CharmBase) -> "State":
@@ -177,9 +183,24 @@ def from_charm(cls, charm: ops.CharmBase) -> "State":
         # Get websocket_mode config
         websocket_mode = bool(charm.model.config.get("websocket_mode", True))
 
+        # Get user/home config
+        agent_user = str(charm.model.config.get("agent_user", "jenkins") or "jenkins")
+        jenkins_home = Path(
+            str(charm.model.config.get("jenkins_home", "/var/lib/jenkins") or "/var/lib/jenkins")
+        )
+        if (
+            not _AGENT_USER_PATTERN.fullmatch(agent_user)
+            or not _JENKINS_HOME_PATTERN.fullmatch(str(jenkins_home))
+            or jenkins_home == Path("/")
+            or ".." in jenkins_home.parts
+        ):
+            raise InvalidStateError("Invalid agent configuration.")
+
         return cls(
             agent_meta=agent_meta,
             agent_relation_credentials=agent_relation_credentials,
             unit_data=unit_data,
             websocket_mode=websocket_mode,
+            agent_user=agent_user,
+            jenkins_home=jenkins_home,
         )