docs(node): note the verified working directory for relative p2p key paths

README, .env.example, and the clap help for GITLAWB_P2P_KEY now state that a
relative key path is anchored at a verified working directory, and that an
unsafe cwd or ancestor is refused with p2p off while HTTP stays up. Also
normalizes two pre-existing em dashes in the README settings table.

Author: beardthelion

.env.example

@@ -9,12 +9,15 @@ GITLAWB_KEY=/data/keys/identity.pem
 
 # Path to the node's persistent libp2p identity key file. Must include a
 # directory; the node refuses to start on a bare filename, because it will not
-# keep its p2p identity key in the working directory. On Unix it is created
-# 0600 inside a 0700 directory, and a loose key directory is tightened to 0700
-# on start; on other platforms no permissions are enforced. If the node logs
-# that it tightened a loose key directory, treat the key that was sitting there
-# as possibly exposed: delete it so a fresh identity is generated on the next
-# start. Keep it on a persistent volume so the PeerId survives redeploys.
+# keep its p2p identity key in the working directory. With a relative path the
+# node verifies the working directory (ownership and write permissions) before
+# using it; an unsafe cwd or ancestor is refused and p2p stays off while HTTP
+# remains up. On Unix it is created 0600 inside a 0700 directory, and a loose
+# key directory is tightened to 0700 on start; on other platforms no
+# permissions are enforced. If the node logs that it tightened a loose key
+# directory, treat the key that was sitting there as possibly exposed: delete
+# it so a fresh identity is generated on the next start. Keep it on a
+# persistent volume so the PeerId survives redeploys.
 # Default: ~/.gitlawb/p2p.key
 #GITLAWB_P2P_KEY=/data/keys/p2p.key
 

README.md

@@ -391,7 +391,7 @@ Important node settings:
 | `GITLAWB_P2P_PORT` | libp2p QUIC/UDP port. Use `0` to disable. |
 | `GITLAWB_BOOTSTRAP_PEERS` | Comma-separated HTTP peer URLs. |
 | `GITLAWB_P2P_BOOTSTRAP` | Comma-separated libp2p multiaddrs. |
-| `GITLAWB_P2P_KEY` | Path to the node's persistent libp2p identity key file, which fixes the PeerId across restarts. Must name a key file inside a directory, such as `/data/keys/p2p.key` or `./keys/p2p.key`; bare filenames, directory paths, trailing `/`, and the filesystem root are refused at startup. On Unix a new key is created `0600` inside a `0700` directory; a loose key directory is tightened to `0700` on start. An existing key copied from backup with group or other bits set is rejected rather than repaired; run `chmod 600` on it before restarting. P2P stays off while HTTP remains up if the key cannot be loaded. On other platforms no permissions are enforced. Default `~/.gitlawb/p2p.key`; point it at a persistent volume when running in a container. |
+| `GITLAWB_P2P_KEY` | Path to the node's persistent libp2p identity key file, which fixes the PeerId across restarts. Must name a key file inside a directory, such as `/data/keys/p2p.key` or `./keys/p2p.key`; bare filenames, directory paths, trailing `/`, and the filesystem root are refused at startup. With a relative path the node verifies the working directory (ownership and write permissions) before using it. On Unix a new key is created `0600` inside a `0700` directory; a loose key directory is tightened to `0700` on start. An existing key copied from backup with group or other bits set is rejected rather than repaired; run `chmod 600` on it before restarting. P2P stays off while HTTP remains up if the key cannot be loaded, including when an unsafe ancestor or working directory is refused. On other platforms no permissions are enforced. Default `~/.gitlawb/p2p.key`; point it at a persistent volume when running in a container. |
 | `GITLAWB_BOOTSTRAP_DISABLE_SEEDS` | Disable embedded seed peers for isolated dev/test networks. |
 | `GITLAWB_REQUIRE_SIGNED_PEER_WRITES` | Require signed peer announce/sync writes. Defaults to `false` during the staged rollout below. |
 | `GITLAWB_ENFORCE_OWNER_PUSH` | Require the authenticated pusher to be the repo owner on `git-receive-pack`. **Defaults to `true`.** A `did:key` signature is authentication, not authorization — anyone can mint a key and sign — so with this off every signed caller may push to every repository, private ones included. Delegated and CI keys count as non-owners: a UCAN `git/push` capability is verified but not yet honored for authorization, so they cannot push while this is on. Set `false` only for a rolling upgrade; see [`docs/RUN-A-NODE.md`](docs/RUN-A-NODE.md). |

crates/gitlawb-node/src/config.rs

@@ -120,7 +120,9 @@ pub struct Config {
     #[arg(long, env = "GITLAWB_P2P_PORT", default_value_t = 7546)]
     pub p2p_port: u16,
 
-    /// Path to the persistent libp2p identity key
+    /// Path to the persistent libp2p identity key. With a relative path the
+    /// node verifies the working directory (ownership and write permissions)
+    /// before using it.
     #[arg(long, env = "GITLAWB_P2P_KEY", default_value = "~/.gitlawb/p2p.key")]
     pub p2p_key_path: String,
 

crates/gitlawb-node/src/p2p/mod.rs

@@ -471,8 +471,9 @@ fn verify_and_create_ancestor_chain(dir: &Path, euid: u32) -> Result<()> {
             )
         };
         if fd < 0 {
-            return Err(std::io::Error::last_os_error())
-                .with_context(|| format!("failed to open the filesystem root for {}", dir.display()));
+            return Err(std::io::Error::last_os_error()).with_context(|| {
+                format!("failed to open the filesystem root for {}", dir.display())
+            });
         }
         (OwnedFd(fd), PathBuf::from("/"))
     } else {
@@ -487,8 +488,9 @@ fn verify_and_create_ancestor_chain(dir: &Path, euid: u32) -> Result<()> {
             )
         };
         if fd < 0 {
-            return Err(std::io::Error::last_os_error())
-                .with_context(|| format!("failed to open the working directory for {}", dir.display()));
+            return Err(std::io::Error::last_os_error()).with_context(|| {
+                format!("failed to open the working directory for {}", dir.display())
+            });
         }
         let display = std::env::current_dir()
             .map(|d| {
@@ -553,7 +555,9 @@ fn verify_and_create_ancestor_chain(dir: &Path, euid: u32) -> Result<()> {
                             format!(
                                 "failed to create key directory component {} below {}",
                                 name.to_string_lossy(),
-                                acc.parent().map(|p| p.display().to_string()).unwrap_or_default()
+                                acc.parent()
+                                    .map(|p| p.display().to_string())
+                                    .unwrap_or_default()
                             )
                         });
                     }
@@ -1919,7 +1923,11 @@ mod tests {
         assert_eq!(keys_mode & 0o777, 0o700, "key directory must be owner-only");
 
         let key_mode = std::fs::metadata(&path).unwrap().permissions().mode();
-        assert_eq!(key_mode & 0o777, 0o600, "key file must be owner-read/write only");
+        assert_eq!(
+            key_mode & 0o777,
+            0o600,
+            "key file must be owner-read/write only"
+        );
 
         println!("p2p-key-multilevel: asserted");
     }
@@ -2903,7 +2911,10 @@ mod tests {
                 "mode {mode:04o} must be refused for group write, got: {msg}"
             );
             // Refusal must not create the key directory or the key.
-            assert!(!ancestor.join("keys").exists(), "key dir must not be created");
+            assert!(
+                !ancestor.join("keys").exists(),
+                "key dir must not be created"
+            );
             assert!(!path.exists(), "key must not be created");
         }
     }
@@ -2958,7 +2969,10 @@ mod tests {
             "intermediate symlink refusal must name the symlink, got: {err:#}"
         );
         // The symlink target must be untouched: no keys dir, no key inside.
-        assert!(!real.join("keys").exists(), "symlink target must be untouched");
+        assert!(
+            !real.join("keys").exists(),
+            "symlink target must be untouched"
+        );
     }
 
     #[cfg(unix)]