Skip to content

The agent that grows with you

feat(nix): the session token rides the unit environment as a path

ethernet7c8d7b9cf35a
diff --git a/nix/checks.nix b/nix/checks.nix
index 42f6fb1326e..3f01aa3f8a2 100644
--- a/nix/checks.nix
+++ b/nix/checks.nix
@@ -488,19 +488,31 @@ json.dump(sorted(leaf_paths(DEFAULT_CONFIG)), sys.stdout, indent=2)
agentPackages = builtins.filter (p: (p.pname or "") == "hermes-agent") cfg.home.packages;
# The backend of the service, as the unit or the agent runs it.
+ backendArgvList =
+ if pkgs.stdenv.hostPlatform.isDarwin then
+ cfg.launchd.agents.hermes-backend.config.ProgramArguments
+ else
+ [ cfg.systemd.user.services.hermes-backend.Service.ExecStart ];
+ backendArgvText = lib.concatStringsSep " " (lib.flatten backendArgvList);
backendScript =
let
- argv =
- if pkgs.stdenv.hostPlatform.isDarwin then
- cfg.launchd.agents.hermes-backend.config.ProgramArguments
- else
- [ cfg.systemd.user.services.hermes-backend.Service.ExecStart ];
- first = lib.head (lib.flatten argv);
# writeShellScript gives a store path. Read the real text, so
# the check tests the script and not the option that made it.
- path = lib.head (lib.splitString " " first);
+ path = lib.head (lib.splitString " " (lib.head (lib.flatten backendArgvList)));
in
builtins.readFile path;
+ # The unit text that carries the token's path: an Environment
+ # list (systemd) or an EnvironmentVariables set (launchd).
+ backendTokenText =
+ # Same NAME=value shape on both platforms, so one assertion
+ # covers each: systemd renders an Environment list, launchd an
+ # attribute set that holds the bare value.
+ if pkgs.stdenv.hostPlatform.isDarwin then
+ "HERMES_DASHBOARD_SESSION_TOKEN_FILE="
+ + (cfg.launchd.agents.hermes-backend.config.EnvironmentVariables.HERMES_DASHBOARD_SESSION_TOKEN_FILE
+ or "")
+ else
+ lib.concatStringsSep "\n" cfg.systemd.user.services.hermes-backend.Service.Environment;
failures =
lib.optional (
@@ -524,20 +536,34 @@ json.dump(sorted(leaf_paths(DEFAULT_CONFIG)), sys.stdout, indent=2)
++ lib.optional (
!lib.hasInfix "HERMES_DESKTOP_REMOTE_TOKEN" wrapper
) "the launcher must give a token with the URL: the desktop resolver throws when the URL is set alone"
- ++ lib.optional (
- !lib.hasInfix "HERMES_DASHBOARD_SESSION_TOKEN" backendScript
- ) "the backend must read the session token, or it makes a new one that the application cannot know"
# ── The token never enters the Nix store ────────────────────
- # Each side must read the file at start time. A --set flag or
- # an Environment= value writes the literal into a store path
- # that all users can read.
+ # The desktop launcher reads the file at start time (--run, not
+ # --set: a --set value writes the token into a store path that
+ # all users can read). The backend unit instead carries the
+ # token's PATH in its environment and hermes reads the file
+ # itself, so the store never sees the token either way.
++ lib.optional (
!lib.hasInfix tokenFile wrapper || !lib.hasInfix "--run" wrapper
) "the launcher must read the token from ${tokenFile} at start time, with --run"
++ lib.optional (
- !lib.hasInfix tokenFile backendScript
- ) "the backend must read the token from ${tokenFile} at start time"
+ !lib.hasInfix "HERMES_DASHBOARD_SESSION_TOKEN_FILE=${tokenFile}" backendTokenText
+ ) "the backend unit must name the token file in its environment, or hermes mints a token the application cannot know"
+ # With no waitFor, a token must no longer force the launcher:
+ # nothing in the command line has to read a secret any more.
+ ++ lib.optional (
+ lib.hasInfix "hermes-backend-launch" backendArgvText
+ ) "a sessionTokenFile alone must not force the launcher; the token path rides in the unit environment (got: ${backendArgvText})"
+
+ # Secret managers leave a "$XDG_RUNTIME_DIR" placeholder in
+ # secret paths for a shell to expand (agenix's Home Manager
+ # module does). escapeShellArg freezes the placeholder into a
+ # literal, so the desktop reader must expand it before its
+ # readability check. The backend takes the path from the unit
+ # environment verbatim, so nothing renders it through a shell.
+ ++ lib.optional (
+ !lib.hasInfix ''_token_file=''${_token_file//\$\{XDG_RUNTIME_DIR\}/''${XDG_RUNTIME_DIR:-}}'' wrapper
+ ) "the desktop launcher must expand an unexpanded \"$XDG_RUNTIME_DIR\" in the token path"
++ lib.optional (
setValue "HERMES_DESKTOP_REMOTE_TOKEN" != null
) "the token must never be a --set value: makeWrapper writes it into the world-readable Nix store";
@@ -1020,12 +1046,19 @@ json.dump(sorted(leaf_paths(DEFAULT_CONFIG)), sys.stdout, indent=2)
waitFor = null;
interfaceName = null;
waitTimeout = 120;
- # No token here: this case asserts the plain argv, which the
- # module builds only when nothing must run before the
- # backend. A token needs the launcher script instead.
+ # No token here: this case asserts the plain argv. The
+ # withToken case below proves a token alone still yields the
+ # same plain argv -- only a wait needs the launcher.
sessionTokenFile = null;
};
};
+ withToken =
+ (cfgFor "serve")
+ // {
+ backend = (cfgFor "serve").backend // {
+ sessionTokenFile = "/run/secrets/hermes-argv-probe-token";
+ };
+ };
sentinel = "--hermes-nix-argv-probe";
probe = argv: lib.escapeShellArgs (argv ++ [ sentinel ]);
in
@@ -1058,6 +1091,7 @@ json.dump(sorted(leaf_paths(DEFAULT_CONFIG)), sys.stdout, indent=2)
check "gateway" ${probe (common.gatewayArgv (cfgFor "none"))}
check "serve" ${probe (common.backendArgv { inherit pkgs; cfg = cfgFor "serve"; })}
check "dashboard" ${probe (common.backendArgv { inherit pkgs; cfg = cfgFor "dashboard"; })}
+ check "serve+token" ${probe (common.backendArgv { inherit pkgs; cfg = withToken; })}
mkdir -p $out
echo "ok" > $out/result
diff --git a/nix/homeManagerModules.nix b/nix/homeManagerModules.nix
index cbffaffce78..6c990086662 100644
--- a/nix/homeManagerModules.nix
+++ b/nix/homeManagerModules.nix
@@ -101,11 +101,18 @@
# The token is read at start time and never with `--set`. makeWrapper
# writes a --set value into the Nix store, which all users can read.
desktopRun = lib.optional desktopUsesService ''
- if [ -r ${lib.escapeShellArg cfg.backend.sessionTokenFile} ]; then
- HERMES_DESKTOP_REMOTE_TOKEN="$(tr -d '\r\n' < ${lib.escapeShellArg cfg.backend.sessionTokenFile})"
+ _token_file=${lib.escapeShellArg cfg.backend.sessionTokenFile}
+
+ # Secret managers leave a "$XDG_RUNTIME_DIR" placeholder in secret
+ # paths for a shell to expand (agenix's Home Manager module does).
+ # escapeShellArg froze it into a literal, so expand it here.
+ _token_file=''${_token_file//\$\{XDG_RUNTIME_DIR\}/''${XDG_RUNTIME_DIR:-}}
+
+ if [ -r "$_token_file" ]; then
+ HERMES_DESKTOP_REMOTE_TOKEN="$(tr -d '\r\n' < "$_token_file")"
export HERMES_DESKTOP_REMOTE_TOKEN
else
- echo "hermes-desktop: cannot read the session token at ${cfg.backend.sessionTokenFile}." >&2
+ echo "hermes-desktop: cannot read the session token at $_token_file." >&2
echo "hermes-desktop: the application starts its own backend instead of the one of the service." >&2
fi
'';
@@ -122,6 +129,7 @@
{
description,
argv,
+ environment ? { },
}:
{
Unit = {
@@ -134,9 +142,12 @@
Install.WantedBy = [ "default.target" ];
Service = {
Type = "simple";
- Environment = (lib.mapAttrsToList (k: v: "${k}=${v}") processEnvironment) ++ [
- "PATH=${unitPath}"
- ];
+ Environment =
+ (lib.mapAttrsToList (k: v: "${k}=${v}") processEnvironment)
+ ++ (lib.mapAttrsToList (k: v: "${k}=${lib.escapeShellArg v}") environment)
+ ++ [
+ "PATH=${unitPath}"
+ ];
ExecStart = lib.escapeShellArgs argv;
WorkingDirectory = cfg.workingDirectory;
Restart = cfg.restart;
@@ -150,15 +161,22 @@
};
mkAgent =
- { argv, logName }:
+ {
+ argv,
+ logName,
+ environment ? { },
+ }:
{
enable = true;
config = {
Label = "org.nix-community.home.${logName}";
ProgramArguments = argv;
- EnvironmentVariables = processEnvironment // {
- PATH = "${unitPath}:/usr/bin:/bin:/usr/sbin:/sbin";
- };
+ EnvironmentVariables =
+ processEnvironment
+ // environment
+ // {
+ PATH = "${unitPath}:/usr/bin:/bin:/usr/sbin:/sbin";
+ };
WorkingDirectory = cfg.workingDirectory;
RunAtLoad = true;
KeepAlive =
@@ -404,6 +422,7 @@
systemd.user.services.hermes-backend = mkUnit {
description = common.backendDescription cfg;
argv = common.backendArgv { inherit pkgs cfg; };
+ environment = common.backendSessionEnvironment { inherit cfg; };
};
})
@@ -419,6 +438,7 @@
launchd.agents.hermes-backend = mkAgent {
argv = common.backendArgv { inherit pkgs cfg; };
logName = "hermes-backend";
+ environment = common.backendSessionEnvironment { inherit cfg; };
};
})
]
diff --git a/nix/moduleCommon.nix b/nix/moduleCommon.nix
index c0ec824be81..07d23358a8f 100644
--- a/nix/moduleCommon.nix
+++ b/nix/moduleCommon.nix
@@ -947,14 +947,16 @@ let
]
++ cfg.backend.extraArgs;
- # The launcher that reads the session token, waits for the bind target,
- # then starts the backend.
+ # The launcher that waits for the bind target, then starts the backend.
#
- # The token cannot go in the unit environment. A systemd `Environment=`
- # value and a launchd EnvironmentVariables value both land in the Nix
- # store, which all users can read. Thus the launcher reads the file at
- # start time. launchd has no EnvironmentFile, so a script is the one shape
- # that works on both hosts.
+ # The token never rides through this script: it travels as a file path in
+ # the unit environment (backendSessionEnvironment), which is not a secret,
+ # and hermes reads the file itself at startup
+ # (HERMES_DASHBOARD_SESSION_TOKEN_FILE). A shell wrapper that read the file
+ # had to escapeShellArg the path, which froze any "${XDG_RUNTIME_DIR}"
+ # placeholder into a literal and crash-looped the unit (agenix's Home
+ # Manager module default). Set an absolute path instead; see the option
+ # description.
#
# `exec` on the last line keeps hermes as the MainPID of the unit. No shell
# stays in the cgroup, and the restart logic of systemd sees the real
@@ -971,25 +973,6 @@ let
_timeout=${toString cfg.backend.waitTimeout}
_waited=0
- ${lib.optionalString (cfg.backend.sessionTokenFile != null) ''
- # Read the token, and never put it on a command line. A command
- # line is visible to each process on the host.
- _token_file=${lib.escapeShellArg cfg.backend.sessionTokenFile}
-
- if [ ! -r "$_token_file" ]; then
- echo "hermes-backend: cannot read the session token file '$_token_file'. The unit stops." >&2
- echo "hermes-backend: backend.sessionTokenFile must name a runtime path that this user can read." >&2
- exit 1
- fi
-
- HERMES_DASHBOARD_SESSION_TOKEN="$(${pkgs.coreutils}/bin/tr -d '\r\n' < "$_token_file")"
- export HERMES_DASHBOARD_SESSION_TOKEN
-
- if [ -z "$HERMES_DASHBOARD_SESSION_TOKEN" ]; then
- echo "hermes-backend: the session token file '$_token_file' is empty. The unit stops." >&2
- exit 1
- fi
- ''}
${
if cfg.backend.waitFor == null then
''
@@ -1054,12 +1037,31 @@ let
''
);
+ # The session token travels as a file path, never as the token itself. A
+ # path is not a secret, so it can sit in a systemd Environment= or a
+ # launchd EnvironmentVariables value without putting anything readable
+ # into the store, and hermes reads the file itself at startup
+ # (HERMES_DASHBOARD_SESSION_TOKEN_FILE), failing loudly when the file is
+ # missing or empty.
+ #
+ # The path must be absolute. A "$XDG_RUNTIME_DIR"-style placeholder that a
+ # secret manager left for a shell to expand is passed through verbatim and
+ # nothing expands it here; agenix's home-manager module default is such a
+ # placeholder, so pin `age.secrets.<name>.path` to
+ # /run/user/<uid>/agenix/<name>.
+ backendSessionEnvironment =
+ { cfg }:
+ lib.optionalAttrs (cfg.backend.sessionTokenFile != null) {
+ HERMES_DASHBOARD_SESSION_TOKEN_FILE = cfg.backend.sessionTokenFile;
+ };
+
backendArgv =
{ pkgs, cfg }:
# A plain argv is enough only when nothing must run before the backend.
- # A wait needs the address at start time, and a token must be read from
- # a file that the store must never hold. Either one needs the launcher.
- if cfg.backend.waitFor == null && cfg.backend.sessionTokenFile == null then
+ # A wait needs the address at start time, so it needs the launcher. The
+ # token does not: it travels as a file path in the unit environment and
+ # hermes reads the file itself.
+ if cfg.backend.waitFor == null then
backendCommand cfg cfg.backend.host
else
[ "${backendLauncher { inherit pkgs cfg; }}" ];
@@ -1179,6 +1181,7 @@ in
backendArgv
backendBindAssertions
backendDescription
+ backendSessionEnvironment
deepConfigType
effectivePackage
gatewayArgv
diff --git a/nix/nixosModules.nix b/nix/nixosModules.nix
index 328880a1e5b..1c938178f3a 100644
--- a/nix/nixosModules.nix
+++ b/nix/nixosModules.nix
@@ -236,7 +236,8 @@
commonUnitEnvironment = {
HOME = cfg.stateDir;
}
- // common.processEnvironment { inherit hermesHome; };
+ // common.processEnvironment { inherit hermesHome; }
+ // common.backendSessionEnvironment { inherit cfg; };
unitPath = common.processPath { inherit pkgs cfg; };