// Package socket owns the daemon's Unix-domain-socket listener, the per-OS
// peer-credential capture, and the length-prefix message framing.
//
// ADR-0010 specifies SOCK_SEQPACKET, but macOS does not support SEQPACKET on
// AF_UNIX (only SOCK_STREAM and SOCK_DGRAM). Phase 1 uses SOCK_STREAM uniformly
// on Linux and macOS with a 4-byte big-endian length prefix per frame. Peer
// credentials are still reliably retrievable on stream sockets via
// SO_PEERCRED (Linux) / LOCAL_PEERCRED + LOCAL_PEEREPID (macOS), so the
// transport simplification does not affect the trust model. A follow-up issue
// should amend ADR-0010 to record the per-OS transport types.
package socket

// PeerCred is the OS-attested identity of a connecting emitter, captured at
// accept() time before any frame is read. The agent's self-asserted identity
// in the frame body is untrusted; this is what makes the audit meaningful.
type PeerCred struct {
	// Platform discriminates which fields are populated. One of
	// "linux", "darwin". A future Windows port will introduce additional
	// values and fields (user_sid, integrity_level).
	Platform string

	// PID is the connecting process's process id. Signed because POSIX pid_t
	// is signed (and -1 is a valid sentinel).
	PID int32

	// UID, GID are POSIX credentials. uid_t and gid_t are unsigned 32-bit on
	// every platform we support, so widen-and-format via uint64 to preserve
	// the full range — narrowing into int32 here would wrap UIDs above
	// 2^31 to negative values and corrupt the recorded peer.
	UID uint32
	GID uint32

	// ExePath is the absolute path to the connecting process's executable,
	// or "" when the daemon could not resolve it. On Linux this is read from
	// /proc/<pid>/exe; on macOS via the SYS_PROC_INFO(PROC_PIDPATHINFO)
	// syscall (the call libproc's proc_pidpath() wraps). Failure is
	// non-fatal — the daemon still records pid/uid/gid.
	ExePath string
}
