fix(node): reconcile public-read messaging with per-repo enforcement

GITLAWB_PUBLIC_READ is read nowhere except a startup warning, while
read enforcement actually happens per repository through is_public and
path-scoped visibility rules. The flag's help text, the startup
warning, .env.example, and the readiness audit all still claimed
private-read enforcement was unwired.

The help and warning now state the flag is reserved and inert, and
point at the real per-repo control. A config test asserts the rendered
help neither claims enforcement is missing nor omits that the flag
does nothing.

Closes #338.

Author: beardthelion

.env.example

@@ -108,8 +108,8 @@ GITLAWB_ENFORCE_OWNER_PUSH=true
 GITLAWB_P2P_BOOTSTRAP=
 
 # ── Access control ────────────────────────────────────────────────────────
-# Reserved for private-read mode. Public/private repo read enforcement is not
-# wired in the current live release; do not rely on this for private repositories.
+# Reserved and currently inert. Repo reads are gated per repository by
+# is_public and path-scoped visibility rules; this flag changes nothing.
 GITLAWB_PUBLIC_READ=true
 
 # Maximum git smart-HTTP pack request size, in bytes.

crates/gitlawb-node/src/config.rs

@@ -55,7 +55,10 @@ pub struct Config {
     #[arg(long, env = "GITLAWB_KEY", default_value = "~/.gitlawb/identity.pem")]
     pub key_path: String,
 
-    /// Reserved for private-read mode; per-repo read enforcement is not wired in alpha
+    /// Reserved and currently inert: read access is enforced per repository
+    /// through `is_public` and path-scoped visibility rules, not this flag.
+    /// Setting it to false changes nothing; make a repo private through its
+    /// own visibility instead.
     #[arg(long, env = "GITLAWB_PUBLIC_READ", default_value_t = true)]
     pub public_read: bool,
 
@@ -1424,6 +1427,28 @@ mod tests {
         );
     }
 
+    /// #338: GITLAWB_PUBLIC_READ is inert, so its help must not claim read
+    /// enforcement is missing; it must tell the operator the flag changes
+    /// nothing and where the real control lives.
+    #[test]
+    fn public_read_help_describes_the_flag_as_inert() {
+        use clap::CommandFactory;
+        let cmd = Config::command();
+        let arg = cmd
+            .get_arguments()
+            .find(|a| a.get_id() == "public_read")
+            .expect("the argument must exist");
+        let help = arg.get_help().map(|h| h.to_string()).unwrap_or_default();
+        assert!(
+            !help.contains("not wired"),
+            "the help still claims read enforcement is unwired: {help}"
+        );
+        assert!(
+            help.contains("inert"),
+            "the help must say the flag is inert so an operator does not rely on it: {help}"
+        );
+    }
+
     /// The flip must not strand an operator mid-upgrade.
     ///
     /// Turning the gate on is a breaking change for any deployment whose pushers are

crates/gitlawb-node/src/main.rs

@@ -110,7 +110,7 @@ async fn main() -> Result<()> {
 
     if !config.public_read {
         warn!(
-            "GITLAWB_PUBLIC_READ=false is reserved; per-repository private-read enforcement is not wired in alpha"
+            "GITLAWB_PUBLIC_READ=false has no effect; reads are gated per repository by is_public and path-scoped visibility rules, not this flag"
         );
     }
 

docs/OSS-READINESS-AUDIT.md

@@ -95,7 +95,7 @@ Live-network blockers to prioritize:
 - GraphQL POST is still open for compatibility; GraphQL mutations should get mutation-aware auth before it becomes a public write API surface.
 - Push authorization is still not capability-complete. A valid DID signature is authentication, not authorization. Owner checks are now enforced on every branch, protected or not (`GITLAWB_ENFORCE_OWNER_PUSH`, on by default); what remains is that a UCAN `git/push` capability is not yet honored, so a delegated or CI key cannot push.
 - UCAN chain validation is incomplete and UCAN revocation/blocklisting is not implemented as an operator feature.
-- Private repository reads are not enforced. `is_public` and `GITLAWB_PUBLIC_READ` exist, but per-repository private-read behavior is not wired.
+- Private repository reads are enforced per repository through `is_public` and path-scoped visibility rules. `GITLAWB_PUBLIC_READ` remains reserved and inert.
 - Peer URLs are self-asserted by DIDs. Signatures prove control of the DID key when present, not ownership/safety of the announced URL.
 - Outbound peer fetch/ping/sync paths should be reviewed for SSRF protections before accepting arbitrary public peer registrations.