[austinvazquez]

Why

A container can forward a host Unix socket into a Nerdbox VM, but a non-root process may not be able to connect to the listener created inside the VM. This prevents workloads such as SSH-agent clients from using the forward without privileged startup steps.

What this changes

• For a uds mount, callers can opt in with numeric uid and gid options. The shim requests mode 0600 and the guest sets the socket's owner and permissions before publishing the listener and starting the container. The guest rejects unsupported modes or reserved ownership values before binding any sockets.
• Mounts without requested ownership send mode 0 and retain the existing listener behavior. The shim and guest versions are coupled; this does not add a System.Info capability probe for older guests.
• The private listener is staged in a protected directory and published with rename. Duplicate-listener preflight, rollback, and identity-aware cleanup protect active or replaced socket paths.
• Connections continue through Nerdbox's forwarder. The raw host socket is not mounted into the container, and its permissions are unchanged.

Validation

• Tests cover mount option parsing, mode propagation, private ownership and permissions, legacy mode, invalid requests, stale-socket replacement, rollback, duplicate listeners, and cleanup.
• Project Checks, unit tests, protobuf, lint, build, fuzz, and integration checks are passing on the PR.

[Copilot]

🟡 Changes recommended

Reserved UID/GID values can silently leave ownership unchanged while the permission-aware RPC reports success.

1 open issue

• Reject reserved UID/GID 4294967295 in BindWithPermissions · New

2 files not reviewed

• api/services/socketforward/v1/socketforward.pb.go: Generated file
• api/services/socketforward/v1/socketforward_ttrpc.pb.go: Generated file

What changed in this PR

Adds private, guest-owned UNIX socket forwarding across the shim and VM boundary.

Changes:

• Adds UID/GID mount options and a permission-aware RPC.
• Creates private listeners with ownership, rollback, and cleanup handling.
• Fixes relay watcher leaks and adds regression tests.

File	Description
internal/​vminit/​socketforward/​socketforward.go	Implements private listeners and cleanup.
internal/​vminit/​socketforward/​socketforward_test.go	Tests permissions, compatibility, and rollback.
internal/​shim/​task/​socketforward.go	Parses ownership options, selects RPC, and fixes watcher cleanup.
internal/​shim/​task/​socketforward_test.go	Tests ownership options and relay completion.
api/​services/​socketforward/​v1/​socketforward.pb.go	Updates generated ownership fields.
api/​services/​socketforward/​v1/​socketforward_ttrpc.pb.go	Adds generated permission-aware RPC bindings.
api/​proto/​nerdbox/​services/​socketforward/​v1/​socketforward.proto	Defines ownership fields and RPC.
api/​next.txtpb	Updates the API descriptor snapshot.

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Aliased RPC socket paths can bypass duplicate protection and disrupt an existing forward.

1 open issue

• Canonicalize socket paths to prevent aliased duplicate binds · New

1 resolved since last review

• Reject reserved UID/GID 4294967295 in BindWithPermissions

2 files not reviewed

• api/services/socketforward/v1/socketforward.pb.go: Generated file
• api/services/socketforward/v1/socketforward_ttrpc.pb.go: Generated file

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

The capability test exceeds macOS Unix-socket path limits, breaking the macOS unit-test job.

1 open issue

• Use TCP listener to avoid macOS Unix socket path limit · New

1 resolved since last review

• Canonicalize socket paths to prevent aliased duplicate binds

2 files not reviewed

• api/services/socketforward/v1/socketforward.pb.go: Generated file
• api/services/system/v1/info.pb.go: Generated file

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Privileged socket publication warrants human security review, and the protobuf-copy issue remains unresolved.

1 open issue

• Avoid copying noncopyable BindRequest over channel · New

1 resolved since last review

• Use TCP listener to avoid macOS Unix socket path limit

2 files not reviewed

• api/services/socketforward/v1/socketforward.pb.go: Generated file
• api/services/system/v1/info.pb.go: Generated file

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

No blocking issues were identified in ownership handling, compatibility checks, or listener cleanup.

No open issues 🎉

1 resolved since last review

• Avoid copying noncopyable BindRequest over channel

2 files not reviewed

• api/services/socketforward/v1/socketforward.pb.go: Generated file
• api/services/system/v1/info.pb.go: Generated file

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Older guests can silently accept private socket requests without applying the requested ownership or permissions.

1 open issue

• Reject private socket binds from legacy RPC handlers · New

1 file not reviewed

• api/services/socketforward/v1/socketforward.pb.go: Generated file

_{Review effort: Balanced}