From a521eab881f7bd9cd60a4528f84c17c489b3b75f Mon Sep 17 00:00:00 2001
From: Bernardo Meurer <beme@anthropic.com>
Date: Wed, 3 Dec 2025 22:52:03 +0000
Subject: [PATCH] home-environment: add home.uid option

Add a home.uid option similar to home.username. When set, the
activation script verifies the current UID matches the expected
value using the new checkUid function.

When using the NixOS or nix-darwin modules, home.uid is
auto-discovered from users.users.<name>.uid when that value
is set.

This is useful for constructing paths that depend on the user's
UID, such as /run/user/<uid> paths for gpg-agent sockets or
other user-specific runtime directories.
---
 modules/home-environment.nix                | 10 ++++++++++
 modules/lib-bash/activation-init.sh         | 11 +++++++++++
 nixos/common.nix                            |  1 +
 tests/modules/home-environment/default.nix  |  2 ++
 tests/modules/home-environment/uid-null.nix |  7 +++++++
 tests/modules/home-environment/uid.nix      |  7 +++++++
 6 files changed, 38 insertions(+)
 create mode 100644 tests/modules/home-environment/uid-null.nix
 create mode 100644 tests/modules/home-environment/uid.nix

diff --git a/modules/home-environment.nix b/modules/home-environment.nix
index 602383608..32c3ce6b5 100644
--- a/modules/home-environment.nix
+++ b/modules/home-environment.nix
@@ -193,6 +193,13 @@ in
       description = "The user's username.";
     };
 
+    home.uid = mkOption {
+      type = types.nullOr types.ints.unsigned;
+      default = null;
+      example = 1000;
+      description = "The user's uid.";
+    };
+
     home.homeDirectory = mkOption {
       type = types.path;
       defaultText = literalExpression ''
@@ -842,6 +849,9 @@ in
           if [[ ! -v SKIP_SANITY_CHECKS ]]; then
             checkUsername ${lib.escapeShellArg config.home.username}
             checkHomeDirectory ${lib.escapeShellArg config.home.homeDirectory}
+            ${lib.optionalString (config.home.uid != null) ''
+              checkUid ${toString config.home.uid}
+            ''}
           fi
 
           ${lib.optionalString config.home.activationGenerateGcRoot ''
diff --git a/modules/lib-bash/activation-init.sh b/modules/lib-bash/activation-init.sh
index b16d8741b..f8fe11037 100755
--- a/modules/lib-bash/activation-init.sh
+++ b/modules/lib-bash/activation-init.sh
@@ -117,6 +117,17 @@ function checkHomeDirectory() {
   fi
 }
 
+function checkUid() {
+  local expectedUid="$1"
+  local actualUid
+  actualUid="$(id -u)"
+
+  if [[ "$actualUid" != "$expectedUid" ]]; then
+    _iError 'Error: UID is "%s" but we expect "%s"' "$actualUid" "$expectedUid"
+    exit 1
+  fi
+}
+
 # Note, the VERBOSE_ECHO variable is deprecated and should not be used inside
 # the Home Manager project. It is provided here for backwards compatibility.
 if [[ -v VERBOSE ]]; then
diff --git a/nixos/common.nix b/nixos/common.nix
index b5bcfa571..68eaa3aa5 100644
--- a/nixos/common.nix
+++ b/nixos/common.nix
@@ -53,6 +53,7 @@ let
 
             home.username = config.users.users.${name}.name;
             home.homeDirectory = config.users.users.${name}.home;
+            home.uid = mkIf (config.users.users.${name}.uid != null) config.users.users.${name}.uid;
 
             # Forward `nix.enable` from the OS configuration. The
             # conditional is to check whether nix-darwin is new enough
diff --git a/tests/modules/home-environment/default.nix b/tests/modules/home-environment/default.nix
index 778982a30..c8dc446b8 100644
--- a/tests/modules/home-environment/default.nix
+++ b/tests/modules/home-environment/default.nix
@@ -3,4 +3,6 @@
   home-session-search-variables = ./session-search-variables.nix;
   home-session-variables = ./session-variables.nix;
   home-nixpkgs-release-check-pkgs = ./nixpkgs-release-check-pkgs.nix;
+  home-uid = ./uid.nix;
+  home-uid-null = ./uid-null.nix;
 }
diff --git a/tests/modules/home-environment/uid-null.nix b/tests/modules/home-environment/uid-null.nix
new file mode 100644
index 000000000..6f1b915c9
--- /dev/null
+++ b/tests/modules/home-environment/uid-null.nix
@@ -0,0 +1,7 @@
+{
+  # home.uid defaults to null, so checkUid should not be called in the activation script
+
+  nmt.script = ''
+    assertFileNotRegex activate "checkUid [0-9]+"
+  '';
+}
diff --git a/tests/modules/home-environment/uid.nix b/tests/modules/home-environment/uid.nix
new file mode 100644
index 000000000..06093971c
--- /dev/null
+++ b/tests/modules/home-environment/uid.nix
@@ -0,0 +1,7 @@
+{
+  home.uid = 1000;
+
+  nmt.script = ''
+    assertFileContains activate "checkUid 1000"
+  '';
+}