nix/host-modules/glue-bao-tls.nix

@@ -193,8 +193,8 @@ in
         # local reads.
         #
         # Its own CN, not the reader's: the reader's leaf carries this hive's
-        # name and its policy reads every agent credential in the swarm, while this
+        # name and its policy reads the whole store, while this principal may
-        # principal may only write one path — which is the entire point of giving the
+        # only write one path — which is the entire point of giving the
         # container an identity instead of lending it the hive's.
         [ -s ${pkiDir}/matrix-ctl.pem ] || ${signLeaf} ${pkiDir} matrix-ctl \
           ${lib.escapeShellArg deployCfg.bao.matrixCtlCommonName} "" clientAuth

nix/host-modules/glue-queue-agent-credential.nix

@@ -45,8 +45,8 @@ let
   # 🩸 This principal's OWN leaf, not `clientCertFile` — the hive's. Bao
   # matches a cert-auth role on the CN, so one leaf shared by four readers
   # would be ONE principal holding the union of four grants: read on
-  # `swarm/agents/*` AND `swarm/hives/<hive>/*`, when this unit reads one
+  # `swarm/agents/*` AND `swarm/hives/<hive>/*` AND `swarm/services/*`, when
-  # queue credential and nothing else. Its own leaf carries
+  # this unit reads one queue credential and nothing else. Its own leaf carries
   # `<queueAgentCommonNamePrefix>-<hive>` and its role grants the single path
   # below — still this hive's own, so the narrowing costs no reach.
   haveClientIdentity =
@@ -141,10 +141,10 @@ in
             a hive that reads the store at all is a hive that needs this pair.
 
             ⚠️ This reader's OWN leaf, not deploy.bao.clientCertFile. That one
-            is the hive's, and its grant reads every agent credential in the
+            is the hive's, and its grant reads every secret in the store; this
-            swarm and this hive's own secrets; this role reads the one
+            role reads the one queue-credential path. Pointing this option at
-            queue-credential path. Pointing this option at the hive's leaf
+            the hive's leaf would evaluate, deploy and log in — and undo the
-            would evaluate, deploy and log in — and undo the split.
+            split.
 
             On a hive that runs the store, glue-bao-tls.nix supplies both as
             defaults and there is nothing to do. Elsewhere the leaf is issued

nix/host-modules/hive-matrix.nix

@@ -412,7 +412,7 @@ in
 
         ⚠️ **Not the hive's own leaf**, and that is the whole deliverable of
         giving this container an identity: the hive's certificate reads every
-        agent credential in the swarm, while this one may write a single path. Pointing
+        secret in the store, while this one may write a single path. Pointing
         this at `deploy.bao.clientCertFile` would evaluate, deploy and work —
         and give away the separation in one line.
 

nix/host-modules/swarm-bao.nix

@@ -802,13 +802,12 @@ let
   # 🩸 Each of these reads exactly ONE path in the store, and does it holding
   # its own leaf rather than `deploy.bao.clientCertFile` — the hive's own leaf,
   # whose policy (`swarm-secret-client`'s `policy::render`) grants read on
-  # `swarm/agents/*` AND `swarm/hives/<hive>/*`, and nothing under
+  # `swarm/agents/*`, `swarm/hives/<hive>/*` AND `swarm/services/*`.
-  # `swarm/services/`.
   # Principals presenting one certificate are ONE principal to bao, so sharing
-  # the hive's leaf would give each of them everything that leaf reads: the
+  # the hive's leaf would leave only the union of what they need expressible:
-  # unit that fetches this hive's queue credential could fetch every agent
+  # the unit that fetches Grafana's OIDC client secret could fetch every agent
-  # credential in the swarm, and a unit that fetches a service's OIDC client
+  # credential in the swarm, and the unit that fetches this hive's queue
-  # secret could not fetch it at all, as that path is not the hive's to read.
+  # credential could fetch Grafana's.
   #
   # Each gets its own leaf, its own cert-auth role and a policy holding the
   # one `secret/data/…` path that principal's script actually names — spelled
@@ -1583,9 +1582,8 @@ in
         the narrowest of the three: its grant is one path, that
         credential itself. The point of the whole arrangement is that the
         process holding the appservice token is not the hive, so handing it
-        the hive's own leaf — which reads every agent credential in the swarm
+        the hive's own leaf — which reads every secret in the store — would
-        and this hive's own secrets — would give the separation away in one
+        give the separation away in one line.
-        line.
 
         ⚠️ Same collision as its siblings, and the same answer: ./swarm.nix
         feeds this value into the guard on
@@ -1887,7 +1885,7 @@ in
         ⚠️ **Not** {option}`services.hyperhive.deploy.bao.clientCertFile`.
         Pointing this at the hive's own leaf would evaluate, deploy and log in —
         and hand a unit that reads one credential a certificate that reads every
-        agent credential in the swarm and this hive's own secrets.
+        secret in the store.
 
         No default here: ./glue-bao-tls.nix points it at the leaf it mints,
         wherever this host mints its own PKI. A deployment that reads a store on
@@ -2283,8 +2281,7 @@ in
             normally gets both from ./glue-bao-tls.nix.
 
             ⚠️ Not deploy.bao.clientCertFile. That one is the hive's, and its
-            grant reads every agent credential in the swarm and this hive's
+            grant reads every secret in the store; this role reads one path.
-            own secrets; this role reads one path.
           '';
         }
         {

nix/host-modules/swarm-grafana.nix

@@ -218,8 +218,8 @@ let
   # 🩸 Grafana's OWN leaf, not `clientCertFile` — the hive's. Bao matches a
   # cert-auth role on the CN, so one leaf shared by four readers would be ONE
   # principal holding the union of four grants: this unit could read every
-  # agent credential in the swarm, when what it needs is the one path
+  # agent credential in the swarm and every other service's OIDC client
-  # `storeSecretPath` names.
+  # secret, when what it needs is the one path `storeSecretPath` names.
   haveClientIdentity =
     baoDeploy.grafanaOidcClientCertFile != null && baoDeploy.grafanaOidcClientKeyFile != null;
 
@@ -432,10 +432,10 @@ in
           band, and every other secret comes from the store with it.
 
           ⚠️ Grafana's OWN leaf, not deploy.bao.clientCertFile. That one is the
-          hive's, and its grant reads every agent credential in the swarm and
+          hive's, and its grant reads every secret in the store; this role
-          this hive's own secrets; this role reads the one path Grafana's
+          reads the one path Grafana's client secret lives at. Pointing this
-          client secret lives at. Pointing this option at the hive's leaf would
+          option at the hive's leaf would evaluate, deploy and log in — and
-          evaluate, deploy and log in — and undo the split.
+          undo the split.
 
           On a hive that runs the store, glue-bao-tls.nix supplies both as
           defaults and there is nothing to do. Elsewhere the leaf is issued

nix/host-modules/swarm-otel.nix

@@ -253,8 +253,8 @@ let
   # 🩸 The collector's OWN leaf, not `clientCertFile` — the hive's. Bao
   # matches a cert-auth role on the CN, so one leaf shared by four readers
   # would be ONE principal holding the union of four grants: this unit could
-  # read every agent credential in the swarm, when what it needs is the one
+  # read every agent credential in the swarm and Grafana's OIDC client
-  # path `storeSecretPath` names.
+  # secret, when what it needs is the one path `storeSecretPath` names.
   haveClientIdentity =
     baoDeploy.otelOidcClientCertFile != null && baoDeploy.otelOidcClientKeyFile != null;
 
@@ -576,10 +576,10 @@ in
           telemetry. That is not this host.
 
           ⚠️ The collector's OWN leaf, not deploy.bao.clientCertFile. That one
-          is the hive's, and its grant reads every agent credential in the
+          is the hive's, and its grant reads every secret in the store; this
-          swarm and this hive's own secrets; this role reads the one path this
+          role reads the one path this collector's client secret lives at.
-          collector's client secret lives at. Pointing this option at the
+          Pointing this option at the hive's leaf would evaluate, deploy and
-          hive's leaf would evaluate, deploy and log in — and undo the split.
+          log in — and undo the split.
 
           On a hive that runs the store, glue-bao-tls.nix supplies both as
           defaults and there is nothing to do. Elsewhere the leaf is issued

nix/module-eval/bao-matrix-reader.nix

@@ -285,9 +285,9 @@ let
       # 🩸 The identity separation this whole arrangement buys, stated as the
       # one thing that would silently undo it. The container gets MATRIX-CTL's
       # leaf — whose grant is a single path — and not the hive's, which reads
-      # every agent credential in the swarm and this hive's own secrets. Both files exist in the same directory and
+      # every secret in the store. Both files exist in the same directory and
       # both would evaluate, deploy and work.
-      name = "matrix-ctl presents its own leaf, never the hive's";
+      name = "matrix-ctl presents its own leaf, never the hive's store-wide one";
       ok =
         let
           env =