fix(ipc): scope the IPC endpoint to the user running the daemon (#1524)

Author: y3owk1n

.agents/skills/add-cli-command/SKILL.md

@@ -6,8 +6,8 @@ description: "Add a Neru CLI command or flag: cobra command in internal/cli, IPC
 # Adding a CLI command to Neru
 
 Neru is a daemon plus a thin CLI: almost every command just serializes an IPC
-request to the running daemon over the Unix socket (`$TMPDIR/neru.sock`) or
-Windows named pipe. A new command therefore touches three layers plus docs —
+request to the running daemon over its per-user Unix socket or Windows named
+pipe. A new command therefore touches three layers plus docs —
 skipping the IPC layer and calling app code directly from `internal/cli` is
 wrong even when it compiles.
 

AGENTS.md

@@ -68,7 +68,7 @@ Hard rules that apply everywhere:
 - **Errors**: use `derrors` (`derrors.New` / `derrors.Wrap`). Unsupported platform behavior returns `derrors.CodeNotSupported` explicitly — never a silent no-op; callers degrade via `IsNotSupported`.
 - **`modes.Handler` has a strict locking contract** — read `internal/app/modes/AGENTS.md` before touching modes or anything that calls back into the handler.
 
-Runtime shape: a daemon plus a thin CLI. `neru launch` starts the daemon; other commands dial a Unix socket (`$TMPDIR/neru.sock`, 0600) or Windows named pipe — transport in `internal/adapter/ipc`, handlers in `internal/app/ipcctrl`. New user-facing behavior usually needs a CLI command, an IPC handler, and the service/mode work behind it (the `add-cli-command` skill walks it). Startup is a numbered, individually-unwound phase sequence in `internal/app/new.go`. Input flow: native event tap → `adapter/eventtap` → `app/modes/handler.go` → active `Mode` → `app/services/*` → adapter → native API.
+Runtime shape: a daemon plus a thin CLI. `neru launch` starts the daemon; other commands dial a per-user Unix socket (`$XDG_RUNTIME_DIR/neru/neru.sock`, else `$TMPDIR/neru-<uid>/neru.sock`, 0600 in a 0700 directory) or a per-user Windows named pipe (`\\.\pipe\neru-<SID>`) — transport in `internal/adapter/ipc`, handlers in `internal/app/ipcctrl`. The endpoint stays scoped to one user and never widens; `docs/ARCHITECTURE.md` (Runtime Shape) owns the detail. New user-facing behavior usually needs a CLI command, an IPC handler, and the service/mode work behind it (the `add-cli-command` skill walks it). Startup is a numbered, individually-unwound phase sequence in `internal/app/new.go`. Input flow: native event tap → `adapter/eventtap` → `app/modes/handler.go` → active `Mode` → `app/services/*` → adapter → native API.
 
 Configuration is hot-reloadable TOML; adding an option touches five links every time and up to four more when it needs them, with a guardrail test behind most of them — read `internal/config/AGENTS.md` or use the `add-config-option` skill. One of the five is the option's **platform column**: every option, mode flag and action declares which of macOS, Linux and Windows writing it does anything on, beside the vocabulary that owns it, and writing an inert one warns at load rather than refusing (`docs/adr/0013-parity-is-measured-in-words-not-subsystems.md`).
 

SECURITY.md

@@ -58,11 +58,11 @@ Neru does **not**:
 - Send telemetry, analytics, or crash reports.
 - Contact update servers or phone home.
 
-All communication is strictly local — the CLI and daemon talk over a **Unix domain socket** created with owner-only permissions (`0600`) in the system temporary directory.
+All communication is strictly local — the CLI and daemon talk over a **Unix domain socket** on macOS and Linux, and a **named pipe** on Windows.
 
 ### IPC
 
-The CLI communicates with the running daemon via a local Unix socket using a JSON-based message protocol. The socket is not exposed over the network. Only the local user can connect to it.
+The CLI communicates with the running daemon over that endpoint using a JSON-based message protocol. It is never exposed over the network, and it is scoped to the user running the daemon: the socket is mode `0600` inside a `0700` directory that user owns, the named pipe carries that user's SID in its name and a security descriptor naming that SID alone, and on macOS and Linux the daemon additionally reads the connecting process's uid from the kernel and serves only its own. See [ARCHITECTURE.md](docs/ARCHITECTURE.md#runtime-shape) for the exact locations.
 
 ### CGo / Objective-C Bridge
 

docs/ARCHITECTURE.md

@@ -58,10 +58,25 @@ current per-platform support is tracked in
 
 Neru is a **daemon plus a thin CLI**. `neru launch` starts the daemon;
 `neru hints`, `neru action left_click`, `neru config reload` and friends dial a
-Unix domain socket (`$TMPDIR/neru.sock`, mode 0600) or a Windows named pipe —
-see `internal/adapter/ipc` for the transport and
+Unix domain socket or a Windows named pipe — see `internal/adapter/ipc` for the
+transport and
 `internal/app/ipcctrl` for the command handlers.
 
+The endpoint is scoped to one user, in where it lives and in what the daemon
+checks before serving a connection:
+
+- **Unix socket** — `$XDG_RUNTIME_DIR/neru/neru.sock` where the session
+  provides a runtime directory, otherwise `$TMPDIR/neru-<uid>/neru.sock`, mode
+  0600 inside a directory the daemon creates 0700 and owns. The daemon then
+  reads the connecting process's uid from the kernel and serves only its own.
+- **Named pipe** — `\\.\pipe\neru-<SID>`, created with a protected DACL naming
+  that SID alone. There the kernel checks the descriptor before the connection
+  is ever accepted, which is the same question asked earlier.
+
+`neru doctor` prints the endpoint in use. What each *client* can establish
+about the daemon before it connects differs by platform, and is a
+[Known Gap](CROSS_PLATFORM.md#known-gaps) rather than part of this shape.
+
 New user-facing behavior therefore usually needs three pieces: a CLI command
 (`internal/cli/`, registered in an `init()`), an IPC handler, and the
 service/mode work behind it.
@@ -458,8 +473,9 @@ its own.
    key logging.
 2. **Permissions** — Accessibility permission is required on macOS; Neru requests
    only the minimum needed for UI interaction.
-3. **IPC security** — the Unix domain socket is created with restricted file
-   permissions (0600), so only the current user can talk to the daemon.
+3. **IPC security** — the endpoint is scoped to one user, and the daemon checks
+   that for itself rather than trusting the scoping; see Runtime Shape above,
+   which owns the detail.
 
 ---
 

docs/CROSS_PLATFORM.md

@@ -1180,6 +1180,15 @@ working, which is exactly why the build exists.
 11. Font resolution — alias mapping only, no system font enumeration
 12. `neru services` — every subcommand returns `CodeNotSupported`, where macOS
     installs a launchd agent and Linux a systemd user unit
+13. IPC endpoint, client side — the daemon's endpoint is scoped to one user on
+    every platform, but only the Unix client checks that for itself before
+    connecting. A named pipe carries no ownership a client can read without
+    opening it, so the Windows CLI trusts the name it derives from its own SID.
+    The same gap covers the upgrade path: a Unix CLI still reaches a daemon
+    left running on the previous endpoint and gets the version-mismatch message
+    asking for a restart, while on Windows the previous name is named in the
+    failure text rather than dialed, and an old daemon has to be stopped by
+    hand before `neru launch` starts a new one
 
 **macOS**
 

docs/TROUBLESHOOTING.md

@@ -413,8 +413,10 @@ neru launch
 # Check status
 neru status
 
-# If still failing, check for stale socket (path is printed in logs; typically under /var/folders/.../T)
-rm -f /var/folders/*/*/T/neru.sock
+# If still failing, clear a stale socket. The daemon prints its endpoint at
+# startup; both of these are places it can be, and only one will exist.
+rm -f "${XDG_RUNTIME_DIR:-/run/user/$(id -u)}"/neru/neru.sock
+rm -f "${TMPDIR:-/tmp}"/neru-"$(id -u)"/neru.sock
 neru launch
 ```
 
@@ -444,6 +446,26 @@ EOF
 neru launch
 ```
 
+### "Is it running?" right after an upgrade
+
+**The daemon still running is the one the old binary started.**
+
+The IPC endpoint moved to a per-user location (see
+[ARCHITECTURE.md](ARCHITECTURE.md#runtime-shape)), so a daemon that has been up
+since before the upgrade is listening in the old one.
+
+On macOS and Linux the new CLI still finds it and answers with a version
+mismatch asking you to restart the daemon — do that and it moves to the new
+endpoint. On Windows it cannot: stop the old daemon before starting the new
+one, or you end up running two.
+
+**Solution:**
+
+```bash
+pkill neru      # taskkill /IM neru.exe on Windows
+neru launch
+```
+
 ### Daemon stops responding
 
 **IPC socket issue or daemon hung.**
@@ -454,8 +476,10 @@ neru launch
 # Force quit
 pkill -9 neru
 
-# Clean up socket (path is printed in logs; typically under /var/folders/.../T)
-rm -f /var/folders/*/*/T/neru.sock
+# Clean up the socket. The daemon prints its endpoint at startup; both of these
+# are places it can be, and only one will exist.
+rm -f "${XDG_RUNTIME_DIR:-/run/user/$(id -u)}"/neru/neru.sock
+rm -f "${TMPDIR:-/tmp}"/neru-"$(id -u)"/neru.sock
 
 # Restart
 neru launch

internal/adapter/ipc/ipc.go

@@ -46,6 +46,14 @@ const (
 	// DefaultSocketPerms is the default socket permissions.
 	DefaultSocketPerms = 0o600
 
+	// maxCommandBytes bounds one command. A command is a verb, a small
+	// parameter map and its arguments; the largest realistic one — a config
+	// value or a sequence definition traveling in Args — is orders of
+	// magnitude below this. The cap exists so a peer cannot make the daemon
+	// buffer without limit, not to police command shape, which
+	// DisallowUnknownFields already does.
+	maxCommandBytes = 64 << 10
+
 	// defaultBuildVersion is the fallback version when SetBuildVersion is not called.
 	defaultBuildVersion = "dev"
 )
@@ -133,9 +141,43 @@ type Server struct {
 // CommandHandler is the interface for processing IPC commands.
 type CommandHandler func(ctx context.Context, cmd Command) Response
 
-// SocketPath returns the platform IPC endpoint path (Unix socket or named pipe).
+// SocketPath returns the platform IPC endpoint path (Unix socket or named pipe)
+// a client should use.
+//
+// It is the endpoint the daemon listens on in every ordinary case. Where the
+// transport can tell that a live daemon answers somewhere else — an endpoint
+// left by a daemon started before this version, or one in a runtime directory
+// this process's environment does not name — it returns that instead, so a CLI
+// reaches the daemon that is actually running rather than reporting none.
 func SocketPath() string {
-	return endpointPath()
+	return clientEndpointPath()
+}
+
+// errCommandTooLarge is returned by boundedReader once a command has spent its
+// budget. It is a sentinel so the decode failure can be reported as the size
+// refusal it is rather than as the truncated JSON it looks like.
+var errCommandTooLarge = errors.New("command exceeds the maximum size")
+
+// boundedReader is io.LimitReader with a distinguishable ending: hitting the
+// limit is an error rather than a clean EOF.
+type boundedReader struct {
+	reader    io.Reader
+	remaining int64
+}
+
+func (b *boundedReader) Read(buf []byte) (int, error) {
+	if b.remaining <= 0 {
+		return 0, errCommandTooLarge
+	}
+
+	if int64(len(buf)) > b.remaining {
+		buf = buf[:b.remaining]
+	}
+
+	read, err := b.reader.Read(buf)
+	b.remaining -= int64(read)
+
+	return read, err
 }
 
 // NewServer creates a new IPC server instance with the specified handler.
@@ -145,7 +187,9 @@ func NewServer(handler CommandHandler, logger *zap.Logger) (*Server, error) {
 	}
 
 	logger = logger.Named("ipc")
-	socketPath := SocketPath()
+	// The daemon binds the transport's preferred endpoint, never the one
+	// SocketPath may have resolved to some other running daemon's.
+	socketPath := daemonEndpointPath()
 
 	listener, listenerErr := listenEndpoint(context.Background(), socketPath)
 	if listenerErr != nil {
@@ -273,6 +317,17 @@ func (s *Server) handleConnection(connection net.Conn) {
 		s.wg.Done()
 	}()
 
+	// Who is on the other end is settled before anything they sent is read.
+	// A connection that fails this gets no reply at all: there is nothing
+	// useful to tell a caller that should not have reached the daemon, and a
+	// reply would confirm the endpoint to whoever found it.
+	authErr := authorizePeer(connection)
+	if authErr != nil {
+		logger.Warn("Refused an IPC connection from another user", zap.Error(authErr))
+
+		return
+	}
+
 	// Only the read side is bounded here: this guards a client that connects
 	// and never sends a command. The write side gets its own deadline once the
 	// handler has finished, in writeResponse.
@@ -283,7 +338,7 @@ func (s *Server) handleConnection(connection net.Conn) {
 		return
 	}
 
-	decoder := json.NewDecoder(connection)
+	decoder := json.NewDecoder(&boundedReader{reader: connection, remaining: maxCommandBytes})
 	decoder.DisallowUnknownFields()
 
 	encoder := json.NewEncoder(connection)
@@ -306,6 +361,18 @@ func (s *Server) handleConnection(connection net.Conn) {
 
 	decodeCommandErr := decoder.Decode(&cmd)
 	if decodeCommandErr != nil {
+		if errors.Is(decodeCommandErr, errCommandTooLarge) {
+			logger.Error("Refused an oversized command", zap.Int("limit_bytes", maxCommandBytes))
+
+			reply(Response{
+				Success: false,
+				Message: fmt.Sprintf("command exceeds the %d byte limit", maxCommandBytes),
+				Code:    CodeInvalidInput,
+			})
+
+			return
+		}
+
 		logger.Error("Failed to decode command", zap.Error(decodeCommandErr))
 
 		reply(Response{
@@ -422,7 +489,7 @@ func (c *Client) SendWithTimeout(cmd Command, timeout time.Duration) (Response,
 		return Response{}, derrors.Wrap(
 			connectionErr,
 			derrors.CodeIPCFailed,
-			"failed to connect to neru (is it running?)",
+			connectFailureMessage(),
 		)
 	}
 
@@ -510,6 +577,19 @@ func (c *Client) SendWithTimeout(cmd Command, timeout time.Duration) (Response,
 	return response, nil
 }
 
+// connectFailureMessage explains a connection that never got off the ground,
+// adding whatever the transport can say about where else a daemon might be.
+func connectFailureMessage() string {
+	message := "failed to connect to neru (is it running?)"
+
+	hint := endpointHint()
+	if hint != "" {
+		message += "; " + hint
+	}
+
+	return message
+}
+
 // IsServerRunning determines if the IPC server is currently accepting connections.
 // It returns true even when the daemon has a different build version — the
 // version mismatch error will surface when the actual command is sent.

internal/adapter/ipc/ipc_internal_test.go

@@ -3,11 +3,73 @@ package ipc
 import (
 	"encoding/json"
 	"errors"
+	"io"
 	"net"
+	"strings"
 	"testing"
 	"time"
 )
 
+// Running out of budget has to be distinguishable from a stream that simply
+// ended, or an oversized command would be reported as malformed JSON.
+func TestBoundedReader_Read(t *testing.T) {
+	t.Parallel()
+
+	const payload = "hello"
+
+	tests := []struct {
+		name      string
+		input     string
+		remaining int64
+		want      string
+		wantErr   error
+	}{
+		{
+			name:      "reads a payload that fits",
+			input:     payload,
+			remaining: 16,
+			want:      payload,
+			wantErr:   nil,
+		},
+		{
+			// A decoder stops as soon as it has a whole JSON value, so it never
+			// asks for the byte past the budget; io.ReadAll always does.
+			name:      "spends the budget exactly",
+			input:     payload,
+			remaining: 5,
+			want:      payload,
+			wantErr:   errCommandTooLarge,
+		},
+		{
+			name:      "refuses a payload past the budget",
+			input:     payload + " world",
+			remaining: 5,
+			want:      payload,
+			wantErr:   errCommandTooLarge,
+		},
+	}
+
+	for _, testCase := range tests {
+		t.Run(testCase.name, func(t *testing.T) {
+			t.Parallel()
+
+			reader := &boundedReader{
+				reader:    strings.NewReader(testCase.input),
+				remaining: testCase.remaining,
+			}
+
+			read, err := io.ReadAll(reader)
+			if !errors.Is(err, testCase.wantErr) {
+				t.Fatalf("io.ReadAll() error = %v, want %v", err, testCase.wantErr)
+			}
+
+			if string(read) != testCase.want {
+				t.Errorf("io.ReadAll() = %q, want %q", read, testCase.want)
+			}
+		})
+	}
+}
+
 // A handler is free to outlive the deadline set when the connection was
 // accepted — an action sequence can sleep, or wait for the user to finish a
 // mode. The reply must still be attempted, or a command that succeeded would