plan: http gateway rev2 (peer mesh) + validated tunnel spike

- plans/http-gateway.md: rev 2, peer architecture. Control plane routes
  through the local daemon; data plane goes direct to the owning node.
  The CLI stays dumb and holds no credentials.
- internal/gateway: the tunnel is a byte pump between a websocket and the
  angelus socket. Proven with an unmodified jkrpc client: calls,
  notifications, 512KiB frames, and a policy refusal that does not sever
  the connection.
- api/transport: https/wss scheme dials the tunnel and presents it as a
  net.Conn, so jkrpc sees the stream it always saw. Caller is the DAEMON.

Security review returned five CRITICALs, three of which are pre-existing
holes the gateway would have exposed rather than gateway bugs. Recorded
in the plan; C3 (agency methods unguarded on hub sockets) blocks the rest.

Author: gluck

api/transport/transport.go

@@ -1,18 +1,51 @@
 // Package transport defines connection abstractions between components.
-// Endpoints use URI syntax (unix:// or tcp://).
+// Endpoints use URI syntax (unix://, tcp://, or https:// for a remote
+// daemon reached through the HTTP gateway).
 package transport
 
 import (
+	"context"
 	"fmt"
 	"net"
+	"net/http"
+	"strings"
+	"time"
 
+	"github.com/coder/websocket"
 	"github.com/jack-work/jkrpc"
 )
 
 // Endpoint describes how to reach a figaro component (angelus or figaro agent).
 type Endpoint struct {
 	Scheme  string `json:"scheme"`
 	Address string `json:"address"`
+	// Bearer is the credential presented when Scheme is http(s). It is
+	// carried on the Endpoint rather than looked up at dial time so that
+	// exactly one place -- the CLI's origin resolver -- decides which secret
+	// belongs to which host, and nothing below this line reads a keyring.
+	//
+	// It is never serialized: a credential has no business in the JSON an
+	// endpoint travels as (attach responses hand endpoints back to clients).
+	Bearer string `json:"-"`
+}
+
+// Remote reports whether this endpoint leaves the machine. A remote daemon is
+// never auto-started, and pid bindings are meaningless against one.
+func (e Endpoint) Remote() bool {
+	return e.Scheme == "http" || e.Scheme == "https"
+}
+
+// HTTPEndpoint constructs a gateway endpoint from a base URL.
+func HTTPEndpoint(rawURL, bearer string) (Endpoint, error) {
+	u := strings.TrimRight(rawURL, "/")
+	switch {
+	case strings.HasPrefix(u, "https://"):
+		return Endpoint{Scheme: "https", Address: strings.TrimPrefix(u, "https://"), Bearer: bearer}, nil
+	case strings.HasPrefix(u, "http://"):
+		return Endpoint{Scheme: "http", Address: strings.TrimPrefix(u, "http://"), Bearer: bearer}, nil
+	default:
+		return Endpoint{}, fmt.Errorf("origin %q: want an http:// or https:// URL", rawURL)
+	}
 }
 
 // UnixEndpoint is a convenience constructor for unix socket endpoints.
@@ -47,11 +80,60 @@ func DialRaw(ep Endpoint) (net.Conn, error) {
 		return net.Dial("unix", ep.Address)
 	case "tcp":
 		return net.Dial("tcp", ep.Address)
+	case "http", "https":
+		return dialGateway(ep)
 	default:
 		return nil, fmt.Errorf("unsupported transport scheme %q", ep.Scheme)
 	}
 }
 
+// gatewayHandshake bounds the upgrade, not the session. Once the tunnel is
+// open it lives as long as the caller wants: a `listen` may hold it for hours.
+const gatewayHandshake = 30 * time.Second
+
+// dialGateway opens the tunnel: a WebSocket to /v1/socket, presented as a
+// net.Conn so jkrpc sees exactly the stream it always saw. The gateway on
+// the far side copies these bytes to the angelus socket without parsing
+// them, so every method -- including ones added after this code was written
+// -- works across it.
+func dialGateway(ep Endpoint) (net.Conn, error) {
+	ws := "wss"
+	if ep.Scheme == "http" {
+		ws = "ws"
+	}
+	hdr := http.Header{}
+	if ep.Bearer != "" {
+		hdr.Set("Authorization", "Bearer "+ep.Bearer)
+	}
+
+	// The handshake gets a deadline; the resulting conn does not inherit it,
+	// which is why the context is detached below.
+	ctx, cancel := context.WithTimeout(context.Background(), gatewayHandshake)
+	defer cancel()
+
+	c, resp, err := websocket.Dial(ctx, ws+"://"+ep.Address+"/v1/socket",
+		&websocket.DialOptions{HTTPHeader: hdr})
+	if err != nil {
+		if resp != nil {
+			switch resp.StatusCode {
+			case http.StatusUnauthorized, http.StatusForbidden:
+				return nil, fmt.Errorf("gateway %s refused this credential (%s): check `figaro origin`",
+					ep.Address, resp.Status)
+			case http.StatusNotFound:
+				return nil, fmt.Errorf("gateway %s has no tunnel at /v1/socket (%s): is that a figaro gateway?",
+					ep.Address, resp.Status)
+			}
+			return nil, fmt.Errorf("dial gateway %s: %s: %w", ep.Address, resp.Status, err)
+		}
+		return nil, fmt.Errorf("dial gateway %s: %w", ep.Address, err)
+	}
+	// No read limit, for the same reason the gateway sets none: a page
+	// carrying a large tool output is a legitimate frame.
+	c.SetReadLimit(-1)
+	// context.Background, deliberately: the conn outlives the handshake.
+	return websocket.NetConn(context.Background(), c, websocket.MessageBinary), nil
+}
+
 // Listen creates a net.Listener for an endpoint.
 func Listen(ep Endpoint) (net.Listener, error) {
 	switch ep.Scheme {

go.mod

@@ -31,6 +31,7 @@ require (
 	github.com/charmbracelet/bubbles v0.21.1-0.20250623103423-23b8fd6302d7
 	github.com/charmbracelet/bubbletea v1.3.6
 	github.com/charmbracelet/huh v1.0.0
+	github.com/coder/websocket v1.8.15
 	github.com/creack/pty v1.1.24
 	github.com/zalando/go-keyring v0.2.8
 )

go.sum

@@ -76,6 +76,8 @@ github.com/clipperhouse/displaywidth v0.11.0 h1:lBc6kY44VFw+TDx4I8opi/EtL9m20WSE
 github.com/clipperhouse/displaywidth v0.11.0/go.mod h1:bkrFNkf81G8HyVqmKGxsPufD3JhNl3dSqnGhOoSD/o0=
 github.com/clipperhouse/uax29/v2 v2.7.0 h1:+gs4oBZ2gPfVrKPthwbMzWZDaAFPGYK72F0NJv2v7Vk=
 github.com/clipperhouse/uax29/v2 v2.7.0/go.mod h1:EFJ2TJMRUaplDxHKj1qAEhCtQPW2tJSwu5BF98AuoVM=
+github.com/coder/websocket v1.8.15 h1:6B2JPeOGlpff2Uz6vOEH1Vzpi0iUz20A+lPVhPHtNUA=
+github.com/coder/websocket v1.8.15/go.mod h1:NX3SzP+inril6yawo5CQXx8+fk145lPDC6pumgx0mVg=
 github.com/creack/pty v1.1.24 h1:bJrF4RRfyJnbTJqzRLHzcGaZK1NeM5kTC9jGgovnR1s=
 github.com/creack/pty v1.1.24/go.mod h1:08sCNb52WyoAwi2QDyzUCTgcvVFhUzewun7wtTfvcwE=
 github.com/danieljoos/wincred v1.2.3 h1:v7dZC2x32Ut3nEfRH+vhoZGvN72+dQ/snVXo/vMFLdQ=

internal/gateway/filter.go

@@ -0,0 +1,143 @@
+package gateway
+
+// THE FILTER: the one place the tunnel looks at what it carries.
+//
+// A pure pump cannot enforce a method policy, so when a policy is configured
+// the client->daemon direction runs through here instead. The rule that keeps
+// this honest: DECODE TO CHECK, FORWARD THE ORIGINAL. The bytes that reach
+// the daemon are the bytes the client sent, never a re-encoding, so no field
+// this gateway does not know about can be dropped on the way through.
+
+import (
+	"bufio"
+	"encoding/json"
+	"fmt"
+	"io"
+)
+
+// maxFrame bounds one NDJSON line the filter will buffer. A frame larger
+// than this is refused rather than truncated: truncation would change the
+// meaning of what we forward, which is the one thing this file promises not
+// to do.
+const maxFrame = 8 << 20 // 8 MiB
+
+// Decision is a filter's verdict on one method.
+type Decision struct {
+	Allow  bool
+	Reason string
+}
+
+// Filter checks each request's method before forwarding it.
+type Filter struct {
+	// Check is consulted once per request frame. Notifications and responses
+	// from the client (there are none in practice) pass untouched.
+	Check func(method string) Decision
+}
+
+// frame is the sliver of JSON-RPC the filter needs. Everything else in the
+// message is deliberately not modelled: this struct exists to read a method
+// name and an id, not to represent the protocol.
+type frame struct {
+	Method string           `json:"method"`
+	ID     *json.RawMessage `json:"id"`
+}
+
+// Pump copies src to dst, refusing frames the policy denies. A denied
+// request is answered on the CLIENT's stream with a JSON-RPC error carrying
+// its id, so the caller gets a verdict rather than a hang.
+//
+// src must be the client side (we write refusals back to it); dst the daemon.
+func (f *Filter) Pump(src io.ReadWriter, dst io.Writer) error {
+	br := bufio.NewReaderSize(src, 64<<10)
+	// A json.Decoder would be tidier, but it buffers past the value it
+	// returns, and we must forward the EXACT bytes of each message. Reading
+	// discrete NDJSON lines is what makes verbatim forwarding possible.
+	for {
+		line, err := readLine(br, maxFrame)
+		if err != nil {
+			return err
+		}
+		if len(line) == 0 {
+			continue
+		}
+
+		var fr frame
+		if json.Unmarshal(line, &fr) != nil {
+			// Unparseable: let the daemon reject it in its own words. We are
+			// a policy check, not a validator, and inventing an error here
+			// would put this gateway in the business of defining the wire.
+			if _, werr := dst.Write(line); werr != nil {
+				return werr
+			}
+			continue
+		}
+
+		if fr.Method != "" && f.Check != nil {
+			if d := f.Check(fr.Method); !d.Allow {
+				if fr.ID != nil {
+					if werr := writeRefusal(src, *fr.ID, fr.Method, d.Reason); werr != nil {
+						return werr
+					}
+				}
+				continue // never reaches the daemon
+			}
+		}
+
+		if _, werr := dst.Write(line); werr != nil {
+			return werr
+		}
+	}
+}
+
+// readLine returns one NDJSON line INCLUDING its terminating newline, so the
+// bytes forwarded are byte-for-byte what arrived.
+func readLine(br *bufio.Reader, limit int) ([]byte, error) {
+	var buf []byte
+	for {
+		chunk, err := br.ReadSlice('\n')
+		buf = append(buf, chunk...)
+		if len(buf) > limit {
+			return nil, fmt.Errorf("frame exceeds %d bytes", limit)
+		}
+		if err == bufio.ErrBufferFull {
+			continue
+		}
+		if err != nil {
+			if len(buf) > 0 && err == io.EOF {
+				return buf, nil
+			}
+			return nil, err
+		}
+		return buf, nil
+	}
+}
+
+// refusalCode is the JSON-RPC error code for a method the policy refused.
+// It sits in the -32000..-32099 application range and is distinct from the
+// daemon's own codes so a client can tell "the gateway said no" from "the
+// daemon said no".
+const refusalCode = -32040
+
+func writeRefusal(w io.Writer, id json.RawMessage, method, reason string) error {
+	if reason == "" {
+		reason = "refused by gateway policy"
+	}
+	msg := struct {
+		JSONRPC string          `json:"jsonrpc"`
+		ID      json.RawMessage `json:"id"`
+		Error   struct {
+			Code    int    `json:"code"`
+			Message string `json:"message"`
+		} `json:"error"`
+	}{JSONRPC: "2.0", ID: id}
+	msg.Error.Code = refusalCode
+	msg.Error.Message = fmt.Sprintf("%s: %s", method, reason)
+
+	b, err := json.Marshal(msg)
+	if err != nil {
+		return err
+	}
+	b = append(b, '\n')
+	_, err = w.Write(b)
+	return err
+}