Improve auth explain diagnostics

docs/architecture.md

@@ -59,11 +59,13 @@ endpoint candidates, timestamp, signing public key, and an Ed25519 signature
 over a canonical payload. Imported and ping-discovered peer cards are stored as
 untrusted metadata in `peer_cards`; trust reduction is future work. `auth
 explain` reports when a subject is only a discovered peer candidate and denies
-access. The peer ping path authenticates the Iroh endpoint and peer-card
-signature, but it does not authorize any resource module. Protected peer
-control requests must also prove that the signed peer card binds the observed
-Iroh EndpointID, then reduce resource auth ops; an EndpointID alone is not
-accepted as a resource principal.
+access. It also reports whether a trusted node has no endpoint binding, whether
+the discovered peer card has no endpoint bound to that node, or whether a peer
+card endpoint matches the reduced keychain view. The peer ping path
+authenticates the Iroh endpoint and peer-card signature, but it does not
+authorize any resource module. Protected peer control requests must also prove
+that the signed peer card binds the observed Iroh EndpointID, then reduce
+resource auth ops; an EndpointID alone is not accepted as a resource principal.
 
 The daemon starts this endpoint during `geth daemon run` and keeps it alive for
 the daemon lifetime. When endpoint startup succeeds, the Iroh EndpointID is
@@ -309,13 +311,16 @@ both signed logs so the new node can see its approved identity and permissions.
 The authorization plane is `geth-auth`: resource-local signed operation logs,
 grants, revocations, groups, and `auth explain`. Auth operations reduce into a
 current permission view for resources, grants, groups, and bearer access. The
-library can explain direct and group grants. The daemon persists local auth
-grant/revoke operations and `geth auth explain` evaluates that local operation
-log. `geth node grant`, `geth node revoke-grant`, `geth auth grant`, and `geth
-auth revoke` require `--signing-key` in the CLI and store OpenSSH-signed auth
-operations. Enrollment approval uses the same signed auth operation path. Auth
-sync imports only auth operations signed by currently trusted admin keys.
-Broader delegated authority and module enforcement are still future work.
+library can explain direct grants, group grants, missing grants, revoked grants,
+and bearer-secret access. The daemon persists local auth grant/revoke operations
+and `geth auth explain` enriches the reducer result with keychain and discovery
+diagnostics, including discovered-only peers and endpoint-binding state. Human
+output prints those diagnostics and JSON output exposes them as structured
+strings for scripts. `geth node grant`, `geth node revoke-grant`, `geth auth
+grant`, and `geth auth revoke` require `--signing-key` in the CLI and store
+OpenSSH-signed auth operations. Enrollment approval uses the same signed auth
+operation path. Auth sync imports only auth operations signed by currently
+trusted admin keys. Broader delegated authority is still future work.
 
 Capability evaluation supports exact matches plus explicit scoped forms. For KV,
 `kv.write_prefix:<prefix>` grants writes requested as `kv.write_key:<key>` only

docs/roadmap.md

@@ -16,7 +16,7 @@ end-to-end test target for the intended personal mesh use cases.
 
 Implementation order:
 
-1. `[~]` Close remote authorization and replicated-state safety gaps.
+1. `[x]` Close remote authorization and replicated-state safety gaps.
    Acceptance criteria:
    - `[x]` Add initial two-daemon tests proving denied remote pubsub publish,
      remote pipe listen, and SSH admin shell requests do not mutate serving
@@ -27,7 +27,7 @@ Implementation order:
      keychain/auth operations are rejected and not imported.
    - `[x]` Add tests proving conflicting replicated keychain/auth records do
      not mutate trust/resource state.
-   - `[ ]` Improve `auth explain` diagnostics enough for operators to
+   - `[x]` Improve `auth explain` diagnostics enough for operators to
      distinguish discovered-only peers, missing endpoint bindings, missing
      grants, matching grants, revocations, and bearer access.
 
@@ -86,7 +86,7 @@ Implementation order:
     pubsub, pipe, SSH proxy/admin shell, SSH cert metadata, and revocations.
   - `[x]` Initial two-daemon denied-mutation coverage exists for remote pubsub
     publish, remote pipe listen, and SSH admin shell.
-  - `[ ]` `auth explain` output can explain discovered-only peers, missing
+  - `[x]` `auth explain` output can explain discovered-only peers, missing
     endpoint bindings, missing grants, matching grants, revocations, and bearer
     access.
 
@@ -364,6 +364,9 @@ resource-scoped capability decisions.
   - `[x]` Output includes the grant ID or missing grant that caused the result.
   - `[x]` JSON output is stable enough for tests and scripts.
   - `[x]` Replicated auth sync requires trusted-admin signatures before import.
+  - `[x]` Human and JSON output include diagnostics for discovered-only peers,
+    missing and matched endpoint bindings, matching grants, revoked grants, and
+    bearer access.
 
 - `[~]` Resource secrets and bearer invites.
   Acceptance criteria: