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

@@ -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 ''

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

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

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;
 }

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]+"
+  '';
+}

tests/modules/home-environment/uid.nix

@@ -0,0 +1,7 @@
+{
+  home.uid = 1000;
+
+  nmt.script = ''
+    assertFileContains activate "checkUid 1000"
+  '';
+}