From 4028bb5a1dbac4bb2576722424cb7c40b19e7eb1 Mon Sep 17 00:00:00 2001
From: Harivansh Rathi <rathiharivansh@gmail.com>
Date: Wed, 8 Apr 2026 02:47:27 +0000
Subject: [PATCH] feat: freeze ssh and vnc port contracts

Define the minimum machine networking surface for the next host slice and
limit exposed guest ports to SSH and VNC.
---
 contract/machines.go    | 19 ++++++++++---------
 contract/networking.go  | 20 ++++++++++++++++++++
 internal/model/types.go |  4 +++-
 3 files changed, 33 insertions(+), 10 deletions(-)
 create mode 100644 contract/networking.go

diff --git a/contract/machines.go b/contract/machines.go
index a19f30a..7632071 100644
--- a/contract/machines.go
+++ b/contract/machines.go
@@ -3,15 +3,16 @@ package host
 import "time"
 
 type Machine struct {
-	ID             MachineID    `json:"id"`
-	Artifact       ArtifactRef  `json:"artifact"`
-	SystemVolumeID VolumeID     `json:"system_volume_id,omitempty"`
-	UserVolumeIDs  []VolumeID   `json:"user_volume_ids,omitempty"`
-	Phase          MachinePhase `json:"phase"`
-	RuntimeHost    string       `json:"runtime_host,omitempty"`
-	Error          string       `json:"error,omitempty"`
-	CreatedAt      time.Time    `json:"created_at"`
-	StartedAt      *time.Time   `json:"started_at,omitempty"`
+	ID             MachineID     `json:"id"`
+	Artifact       ArtifactRef   `json:"artifact"`
+	SystemVolumeID VolumeID      `json:"system_volume_id,omitempty"`
+	UserVolumeIDs  []VolumeID    `json:"user_volume_ids,omitempty"`
+	RuntimeHost    string        `json:"runtime_host,omitempty"`
+	Ports          []MachinePort `json:"ports,omitempty"`
+	Phase          MachinePhase  `json:"phase"`
+	Error          string        `json:"error,omitempty"`
+	CreatedAt      time.Time     `json:"created_at"`
+	StartedAt      *time.Time    `json:"started_at,omitempty"`
 }
 
 type CreateMachineRequest struct {
diff --git a/contract/networking.go b/contract/networking.go
new file mode 100644
index 0000000..b347beb
--- /dev/null
+++ b/contract/networking.go
@@ -0,0 +1,20 @@
+package host
+
+type MachinePortName string
+
+type PortProtocol string
+
+const (
+	MachinePortNameSSH MachinePortName = "ssh"
+	MachinePortNameVNC MachinePortName = "vnc"
+)
+
+const (
+	PortProtocolTCP PortProtocol = "tcp"
+)
+
+type MachinePort struct {
+	Name     MachinePortName `json:"name"`
+	Port     uint16          `json:"port"`
+	Protocol PortProtocol    `json:"protocol"`
+}
diff --git a/internal/model/types.go b/internal/model/types.go
index 3c83b15..21bac4d 100644
--- a/internal/model/types.go
+++ b/internal/model/types.go
@@ -27,8 +27,10 @@ type MachineRecord struct {
 	Artifact       contracthost.ArtifactRef
 	SystemVolumeID contracthost.VolumeID
 	UserVolumeIDs  []contracthost.VolumeID
-	Phase          contracthost.MachinePhase
 	RuntimeHost    string
+	TapDevice      string
+	Ports          []contracthost.MachinePort
+	Phase          contracthost.MachinePhase
 	Error          string
 	CreatedAt      time.Time
 	StartedAt      *time.Time