Skip to content

Agent Mesh

node: serve assigned egress destinations and decide on method and path

Antonio Ojea81b1122664bf
diff --git a/cmd/sam-node/main.go b/cmd/sam-node/main.go
index aa4adc72..f7edd73b 100644
--- a/cmd/sam-node/main.go
+++ b/cmd/sam-node/main.go
@@ -103,6 +103,7 @@ var (
dhtLookupLimitFlag int
discoveryConcurrencyFlag int
backendProbeTimeoutFlag time.Duration
+ secretsDirFlag string
controlPlaneSyncIntervalFlag time.Duration
)
@@ -496,6 +497,7 @@ func main() {
DHTLookupLimit: dhtLookupLimitFlag,
DiscoveryConcurrency: discoveryConcurrencyFlag,
BackendProbeTimeout: backendProbeTimeoutFlag,
+ SecretsDir: secretsDirFlag,
})
if err != nil {
logger.Fatalf("Failed to initialize mesh node: %v", err)
@@ -566,6 +568,7 @@ func main() {
DHTLookupLimit: dhtLookupLimitFlag,
DiscoveryConcurrency: discoveryConcurrencyFlag,
BackendProbeTimeout: backendProbeTimeoutFlag,
+ SecretsDir: secretsDirFlag,
})
if err != nil {
enrollCancel()
@@ -633,6 +636,7 @@ func main() {
RequiredRole: api.RoleNode,
ControlPlaneSyncInterval: controlPlaneSyncIntervalFlag,
BackendProbeTimeout: backendProbeTimeoutFlag,
+ SecretsDir: secretsDirFlag,
})
if err != nil {
logger.Fatalf("Failed to initialize node after enrollment: %v", err)
@@ -899,6 +903,7 @@ func main() {
runCmd.Flags().IntVar(&discoveryConcurrencyFlag, "discovery-concurrency", 0, "Max concurrent catalog fetches during discovery (0 uses default 10)")
runCmd.Flags().DurationVar(&controlPlaneSyncIntervalFlag, "control-plane-sync-interval", node.DefaultControlPlaneSyncInterval, "How often signing keys, bans, router addresses and mesh policy are pulled from the control plane. Keep it well below the control plane's --key-grace-period; raise it on large meshes.")
runCmd.Flags().DurationVar(&backendProbeTimeoutFlag, "backend-probe-timeout", 0, "Timeout for probing a command-spawned service backend before advertising it (0 uses default 2s); raise this for backends with slower cold-start times")
+ runCmd.Flags().StringVar(&secretsDirFlag, "secrets-dir", node.DefaultSecretsDir, "Directory holding the credentials named by the control plane's egress destinations, one file per credential name")
rootCmd.PersistentFlags().StringVar(&controlPlaneAddr, "control-plane", "", "Control plane URL")
rootCmd.PersistentFlags().BoolVar(&insecureControlPlaneFlag, "insecure-control-plane", false, "Accept a plaintext http:// control plane URL to a non-loopback host (whoever answers it becomes this node's trust root; only for networks you already trust)")
rootCmd.PersistentFlags().StringVar(&configFile, "config", node.DefaultConfigFile, "Path to sam-node.yaml configuration file")
diff --git a/internal/node/config.go b/internal/node/config.go
index 85f79d7c..b86f1932 100644
--- a/internal/node/config.go
+++ b/internal/node/config.go
@@ -108,6 +108,11 @@ func CompleteNodeConfig(config api.NodeConfig) (*NodeConfigComplete, error) {
if err := api.ValidateServiceFormat(svc.Type + "://" + svc.Name); err != nil {
return nil, fmt.Errorf("invalid service config at index %d: %w", i, err)
}
+ // Nodes serve what the control plane assigns them; a destination
+ // declared here would give one node a policy of its own.
+ if t, err := api.ParseServiceType(svc.Type); err == nil && t == api.ServiceType_SERVICE_TYPE_EGRESS {
+ return nil, fmt.Errorf("service %q: egress destinations are assigned by the control plane (PolicyConfig.egress), not declared in the node config", svc.Name)
+ }
if svc.TargetAuthPath != "" && svc.TargetURL == "" {
return nil, fmt.Errorf("service %q: target_auth_path needs a target_url", svc.Name)
}
diff --git a/internal/node/controlplane_sync.go b/internal/node/controlplane_sync.go
index bf02c01f..3d279450 100644
--- a/internal/node/controlplane_sync.go
+++ b/internal/node/controlplane_sync.go
@@ -61,6 +61,9 @@ func (n *SamNode) SyncControlPlane(ctx context.Context) error {
if err := n.syncMeshPolicy(ctx); err != nil {
errs = append(errs, fmt.Errorf("policy: %w", err))
}
+ if err := n.syncEgressAssignments(ctx, controlPlaneURL); err != nil {
+ errs = append(errs, fmt.Errorf("egress: %w", err))
+ }
return errors.Join(errs...)
}
diff --git a/internal/node/discovery_source.go b/internal/node/discovery_source.go
index 8b860cbe..b6cb4441 100644
--- a/internal/node/discovery_source.go
+++ b/internal/node/discovery_source.go
@@ -85,6 +85,9 @@ func serviceKeys(ctx context.Context, svc Service, t api.ServiceType) ([]string,
if lister, ok := svc.(toolLister); ok {
return lister.Tools(ctx)
}
+ case api.ServiceType_SERVICE_TYPE_EGRESS:
+ // The destination name is the only key: callers look a hostname up.
+ return []string{svc.Info().GetName()}, nil
}
return nil, nil
}
diff --git a/internal/node/egress.go b/internal/node/egress.go
new file mode 100644
index 00000000..6dedc4c0
--- /dev/null
+++ b/internal/node/egress.go
@@ -0,0 +1,344 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package node
+
+import (
+ "context"
+ "errors"
+ "fmt"
+ "net/http"
+ "net/http/httputil"
+ "net/url"
+ "os"
+ "path/filepath"
+ "strconv"
+ "strings"
+
+ "github.com/google/sam/api"
+ cpclient "github.com/google/sam/internal/controlplane/client"
+ "google.golang.org/protobuf/proto"
+)
+
+// DefaultSecretsDir is where a node looks for the credentials the control
+// plane names in egress destinations when --secrets-dir is not given.
+const DefaultSecretsDir = "/etc/sam/secrets"
+
+// Proxy-Status error types (RFC 9209) the node answers with when it, and not
+// the destination, refuses a request. A client can then tell a policy denial
+// from a 403 the destination sent.
+const (
+ proxyStatusDenied = "http_request_denied"
+ proxyStatusDestinationNotFound = "destination_not_found"
+ proxyStatusConfigurationError = "proxy_configuration_error"
+)
+
+// refuse answers a request the node refuses itself, naming the reason in
+// Proxy-Status so the client can tell it from the destination's own answer.
+func refuse(w http.ResponseWriter, status int, text, errorType string) {
+ w.Header().Set("Proxy-Status", "sam-node; error="+errorType)
+ http.Error(w, text, status)
+}
+
+// EgressService serves egress://<name>: this node is the HTTP origin for one
+// destination outside the mesh. The destination, where to forward, and which
+// credential to present are the control plane's decision (an
+// EgressDestination that selected this node); the node holds no policy of
+// its own about it. Every request reaches the handler only after Authorize
+// ran with the caller's credential and the method, path, host and port facts.
+type EgressService struct {
+ destination *api.EgressDestination
+ info *api.ServiceInfo
+ target *url.URL
+ secretsDir string
+ handler http.Handler
+}
+
+// newEgressService builds the service for one assignment. The target URL was
+// validated by the control plane; it is parsed again here because this node
+// dials it.
+func newEgressService(d *api.EgressDestination, secretsDir string) (*EgressService, error) {
+ if err := api.ValidateEgressName(d.GetName()); err != nil {
+ return nil, err
+ }
+ target, err := url.Parse(api.EgressTargetURL(d))
+ if err != nil || target.Host == "" || (target.Scheme != "http" && target.Scheme != "https") {
+ return nil, fmt.Errorf("egress %s: invalid target_url", d.GetName())
+ }
+ if target.User != nil {
+ return nil, fmt.Errorf("egress %s: target_url must not carry a credential", d.GetName())
+ }
+ if cred := d.GetCredential(); cred != "" && (filepath.Base(cred) != cred || cred == "." || cred == "..") {
+ return nil, fmt.Errorf("egress %s: credential %q must be a file name", d.GetName(), cred)
+ }
+ return &EgressService{
+ destination: proto.Clone(d).(*api.EgressDestination),
+ info: &api.ServiceInfo{
+ Type: api.ServiceType_SERVICE_TYPE_EGRESS,
+ Name: d.GetName(),
+ Description: "egress to " + target.Scheme + "://" + target.Host,
+ },
+ target: target,
+ secretsDir: secretsDir,
+ }, nil
+}
+
+func (s *EgressService) Info() *api.ServiceInfo { return s.info }
+func (s *EgressService) Handler() http.Handler { return s.handler }
+func (s *EgressService) Teardown() error { return nil }
+
+// Init builds the reverse proxy and confirms the named credential is
+// readable, so a destination whose credential the platform did not deliver is
+// refused here, visibly, instead of answering 502 to every request.
+func (s *EgressService) Init(ctx context.Context) error {
+ if s.destination.GetCredential() != "" {
+ if _, err := s.credential(); err != nil {
+ return err
+ }
+ }
+ proxy := &httputil.ReverseProxy{
+ Rewrite: func(pr *httputil.ProxyRequest) {
+ pr.SetURL(s.target)
+ pr.Out.Host = s.target.Host
+ // What the caller sent authenticated it to the node, and what the
+ // node knows about the caller is for policy; none of it is for the
+ // destination, which sees the node's own credential only.
+ pr.Out.Header.Del("Authorization")
+ pr.Out.Header.Del("Cookie")
+ for name := range pr.Out.Header {
+ if strings.HasPrefix(name, "X-Sam-") || strings.HasPrefix(name, "X-Forwarded-") || name == api.HeaderPeerID {
+ pr.Out.Header.Del(name)
+ }
+ }
+ if auth, ok := pr.In.Context().Value(egressAuthKey{}).(string); ok && auth != "" {
+ pr.Out.Header.Set("Authorization", auth)
+ }
+ },
+ }
+ s.handler = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ auth := ""
+ if s.destination.GetCredential() != "" {
+ // Read per request, so a rotation by the platform applies at once.
+ var err error
+ if auth, err = s.credential(); err != nil {
+ logger.Errorf("[Egress] %s: %v", s.info.Name, err)
+ recordEgressDecision(s.info.Name, egressOutcomeCredentialUnavailable)
+ refuse(w, http.StatusBadGateway, "egress credential unavailable", proxyStatusConfigurationError)
+ return
+ }
+ }
+ proxy.ServeHTTP(w, r.WithContext(context.WithValue(r.Context(), egressAuthKey{}, auth)))
+ })
+ return nil
+}
+
+type egressAuthKey struct{}
+
+// credential reads the named file under the secrets directory and renders it
+// as an Authorization value: "TOKEN" as Bearer, "user:pass" as Basic, the
+// forms target_auth_path accepts.
+func (s *EgressService) credential() (string, error) {
+ name := s.destination.GetCredential()
+ data, err := os.ReadFile(filepath.Join(s.secretsDir, name))
+ if err != nil {
+ return "", fmt.Errorf("credential %q: %w (put the file in %s)", name, errors.Unwrap(err), s.secretsDir)
+ }
+ cred := strings.TrimSpace(string(data))
+ if cred == "" {
+ return "", fmt.Errorf("credential %q is empty", name)
+ }
+ if user, pass, ok := strings.Cut(cred, ":"); ok {
+ return authorizationFor(user, pass), nil
+ }
+ return authorizationFor("", cred), nil
+}
+
+// port is the destination port: explicit in the target URL, or the scheme's.
+func (s *EgressService) port() int {
+ if p := s.target.Port(); p != "" {
+ if n, err := strconv.Atoi(p); err == nil {
+ return n
+ }
+ }
+ if s.target.Scheme == "http" {
+ return 80
+ }
+ return 443
+}
+
+// sameAssignment reports whether the service already serves d as written.
+func (s *EgressService) sameAssignment(d *api.EgressDestination) bool {
+ return s.destination.GetName() == d.GetName() &&
+ api.EgressTargetURL(s.destination) == api.EgressTargetURL(d) &&
+ s.destination.GetCredential() == d.GetCredential()
+}
+
+// egressFactsFor is the host and port an egress request will be sent to,
+// for the authorizer; nil for a service of another type.
+func egressFactsFor(svc Service) *EgressFacts {
+ es, ok := svc.(*EgressService)
+ if !ok {
+ return nil
+ }
+ return &EgressFacts{Host: es.info.Name, Port: es.port()}
+}
+
+// syncEgressAssignments makes the registry's egress services match what the
+// control plane assigned to this node: new and changed destinations are
+// registered, withdrawn ones unregistered. One assignment that cannot be
+// served (a credential the platform did not deliver) is reported and the
+// rest are still applied.
+func (n *SamNode) syncEgressAssignments(ctx context.Context, controlPlaneURL string) error {
+ token := n.GetIdentity()
+ if len(token) == 0 {
+ return errors.New("node has no identity token to fetch egress assignments")
+ }
+ resp, err := controlPlaneClient(controlPlaneURL).FetchEgress(ctx, token)
+ if errors.Is(err, cpclient.ErrNotFound) {
+ // A control plane predating egress destinations assigns none; the
+ // node keeps whatever it serves and does not report an error.
+ logger.Debugf("[Egress] control plane %s has no /egress endpoint; no destinations assigned", controlPlaneURL)
+ return nil
+ }
+ if err != nil {
+ return err
+ }
+ return n.applyEgressAssignments(ctx, resp.GetEgress())
+}
+
+func (n *SamNode) applyEgressAssignments(ctx context.Context, assigned []*api.EgressDestination) error {
+ if n.services == nil {
+ // Before Start there is no registry to reconcile against; Start
+ // applies what arrived last.
+ n.pendingEgressMu.Lock()
+ n.pendingEgress = assigned
+ n.pendingEgressMu.Unlock()
+ return nil
+ }
+ var errs []error
+ var registered, withdrawn, unchanged int
+ wanted := make(map[string]bool, len(assigned))
+ for _, d := range assigned {
+ if d == nil {
+ continue
+ }
+ wanted[d.GetName()] = true
+ if existing, ok := n.services.GetTyped(api.ServiceType_SERVICE_TYPE_EGRESS, d.GetName()); ok {
+ if es, ok := existing.(*EgressService); ok && es.sameAssignment(d) {
+ unchanged++
+ continue
+ }
+ }
+ svc, err := newEgressService(d, n.config.SecretsDir)
+ if err != nil {
+ errs = append(errs, err)
+ continue
+ }
+ if err := n.services.Register(ctx, svc); err != nil {
+ errs = append(errs, fmt.Errorf("egress %s: %w", d.GetName(), err))
+ continue
+ }
+ registered++
+ logger.Infof("[Egress] Serving egress://%s -> %s (assigned by the control plane)", d.GetName(), api.EgressTargetURL(d))
+ }
+ for _, info := range n.services.List(api.ServiceType_SERVICE_TYPE_EGRESS) {
+ if !wanted[info.GetName()] {
+ if err := n.services.Unregister(ctx, info.GetName()); err != nil {
+ errs = append(errs, err)
+ } else {
+ withdrawn++
+ logger.Infof("[Egress] Withdrawn egress://%s (no longer assigned)", info.GetName())
+ }
+ }
+ }
+ // One line per sync that changed something or failed, so "why is my
+ // destination not served" has an answer in the log; a quiet sync is debug.
+ summary := fmt.Sprintf("[Egress] Assignments: %d assigned, %d registered, %d unchanged, %d withdrawn, %d refused", len(assigned), registered, unchanged, withdrawn, len(errs))
+ if registered+withdrawn+len(errs) > 0 {
+ logger.Infof("%s", summary)
+ } else {
+ logger.Debugf("%s", summary)
+ }
+ recordEgressAssignment("registered", registered)
+ recordEgressAssignment("withdrawn", withdrawn)
+ recordEgressAssignment("refused", len(errs))
+ return errors.Join(errs...)
+}
+
+// applyPendingEgress registers the assignments that arrived before the
+// registry existed. Called by Start once it does.
+func (n *SamNode) applyPendingEgress(ctx context.Context) {
+ n.pendingEgressMu.Lock()
+ pending := n.pendingEgress
+ n.pendingEgress = nil
+ n.pendingEgressMu.Unlock()
+ if len(pending) == 0 {
+ return
+ }
+ if err := n.applyEgressAssignments(ctx, pending); err != nil {
+ logger.Warnf("[Egress] applying assignments received before start: %v", err)
+ }
+}
+
+// handleLocalEgress serves /egress/{host}/{path} on the local API: a client
+// of this node asks for a destination this node serves. The caller is this
+// node, so its own credential is evaluated, with the request's method and
+// path and the destination's host and port, and with the agent the client
+// names, as on the mesh datapath. The client's Authorization was for the
+// node and does not travel further.
+func handleLocalEgress(node *SamNode, w http.ResponseWriter, r *http.Request) {
+ if hasDotSegment(r.URL.Path) {
+ http.Error(w, "Invalid path", http.StatusBadRequest)
+ return
+ }
+ host, upstreamPath, _ := strings.Cut(strings.TrimPrefix(r.URL.Path, "/egress/"), "/")
+ host = api.NormalizeMeshHost(host)
+ if host == "" {
+ http.Error(w, "Usage: /egress/<destination>/<path>", http.StatusBadRequest)
+ return
+ }
+ svc, ok := node.services.GetTyped(api.ServiceType_SERVICE_TYPE_EGRESS, host)
+ if !ok || svc.Handler() == nil {
+ recordEgressDecision(host, egressOutcomeNotAssigned)
+ refuse(w, http.StatusNotFound, fmt.Sprintf("no egress destination %q is assigned to this node", host), proxyStatusDestinationNotFound)
+ return
+ }
+ identity := node.GetIdentity()
+ if len(identity) == 0 {
+ http.Error(w, "node has no credential yet", http.StatusServiceUnavailable)
+ return
+ }
+ target := api.EgressServicePrefix + host
+ reqCtx := RequestContext{
+ PeerID: node.Host.ID(),
+ Protocol: "local-api",
+ Target: target,
+ Agent: agentClaim(r.Header.Get(api.HeaderSamAgent)),
+ HTTP: &HTTPRequestFacts{Method: r.Method, Path: "/" + upstreamPath},
+ Egress: egressFactsFor(svc),
+ Local: true,
+ }
+ if err := node.VerifyBiscuitToken(identity, reqCtx); err != nil {
+ recordEgressDecision(host, egressOutcomeDeny)
+ refuse(w, http.StatusForbidden, "Authorization failed", proxyStatusDenied)
+ return
+ }
+ recordEgressDecision(host, egressOutcomeAllow)
+ r.Header.Del(api.HeaderSamBiscuit)
+ r.Header.Del(api.HeaderSamAgent)
+ r.Header.Set(api.HeaderPeerID, node.Host.ID().String())
+ r.URL.Path = "/" + upstreamPath
+ r.URL.RawPath = ""
+ svc.Handler().ServeHTTP(w, r)
+}
diff --git a/internal/node/egress_metrics.go b/internal/node/egress_metrics.go
new file mode 100644
index 00000000..4a3ecb70
--- /dev/null
+++ b/internal/node/egress_metrics.go
@@ -0,0 +1,60 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package node
+
+import (
+ "github.com/prometheus/client_golang/prometheus"
+ "github.com/prometheus/client_golang/prometheus/promauto"
+)
+
+// What an operator running a PEP needs to see: which destinations this node
+// was told to serve and serves, how each request was decided, and whether
+// the credential the platform was supposed to deliver is there. Decisions
+// are labelled by destination and outcome and not by caller, so the series
+// count stays bounded by the policy document and not by the fleet.
+var (
+ egressDecisionsTotal = promauto.NewCounterVec(
+ prometheus.CounterOpts{
+ Name: "sam_node_egress_decisions_total",
+ Help: "Requests for egress destinations this node serves, by destination and outcome (allow, deny, not_assigned, credential_unavailable)",
+ },
+ []string{"destination", "outcome"},
+ )
+
+ egressAssignmentsTotal = promauto.NewCounterVec(
+ prometheus.CounterOpts{
+ Name: "sam_node_egress_assignments_total",
+ Help: "Egress assignments applied from the control plane, by outcome (registered, withdrawn, refused)",
+ },
+ []string{"outcome"},
+ )
+)
+
+const (
+ egressOutcomeAllow = "allow"
+ egressOutcomeDeny = "deny"
+ egressOutcomeNotAssigned = "not_assigned"
+ egressOutcomeCredentialUnavailable = "credential_unavailable"
+)
+
+func recordEgressDecision(destination, outcome string) {
+ egressDecisionsTotal.WithLabelValues(destination, outcome).Inc()
+}
+
+func recordEgressAssignment(outcome string, count int) {
+ if count > 0 {
+ egressAssignmentsTotal.WithLabelValues(outcome).Add(float64(count))
+ }
+}
diff --git a/internal/node/egress_route_test.go b/internal/node/egress_route_test.go
new file mode 100644
index 00000000..dea84e1d
--- /dev/null
+++ b/internal/node/egress_route_test.go
@@ -0,0 +1,213 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package node
+
+import (
+ "context"
+ "net/http"
+ "net/http/httptest"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+ "time"
+
+ "github.com/biscuit-auth/biscuit-go/v2"
+ "github.com/google/sam/api"
+)
+
+// TestLocalEgressRoute is the life of a request from a local client through
+// /egress/{host}/{path}: the node's own credential decides, with the
+// request's method and path and the assignment's host and port; a narrowed
+// grant, the agent the client names and local attenuation all apply; the
+// destination sees the node's credential and none of the client's headers.
+func TestLocalEgressRoute(t *testing.T) {
+ ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+ defer cancel()
+ node, cleanup := startBareNode(t, ctx)
+ defer cleanup()
+
+ var seen []*http.Request
+ upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ seen = append(seen, r.Clone(context.Background()))
+ w.WriteHeader(http.StatusNoContent)
+ }))
+ defer upstream.Close()
+
+ // The node's credential, as the control plane would mint it for a role
+ // selected to serve api.github.com: the serving grant narrowed to GET
+ // under /repos/acme/, and an agent namespace it may speak for.
+ narrowed := api.BuildHTTPGrantFacts(&api.HTTPGrant{Service: "egress://api.github.com", Methods: []string{"GET"}, Paths: []string{"/repos/acme/*"}})
+ facts := append(narrowed,
+ biscuit.Fact{Predicate: biscuit.Predicate{Name: api.FactGrantedAgentSuffix, IDs: []biscuit.Term{biscuit.String(".acme.example")}}},
+ biscuit.Fact{Predicate: biscuit.Predicate{Name: api.FactGrantedServiceExact, IDs: []biscuit.Term{biscuit.String("egress"), biscuit.String("open.example")}}},
+ )
+ token, pub := mintFor(t, node.Host.ID(), facts...)
+ node.SetIdentityCache(token)
+ node.trustedKeys = []TrustedKey{{Key: pub, ReceivedAt: time.Now()}}
+
+ secrets := t.TempDir()
+ if err := os.WriteFile(filepath.Join(secrets, "github-eu"), []byte("ghp_secret"), 0o600); err != nil {
+ t.Fatal(err)
+ }
+ node.config.SecretsDir = secrets
+ cfg, err := CompleteNodeConfig(api.NodeConfig{Attenuation: api.Attenuation{Policies: []string{
+ `deny if path($p), $p.starts_with("/repos/acme/vault");`,
+ }}})
+ if err != nil {
+ t.Fatal(err)
+ }
+ node.nodeConfig = cfg
+ if err := node.applyEgressAssignments(ctx, []*api.EgressDestination{
+ {Name: "api.github.com", TargetUrl: upstream.URL, Credential: "github-eu"},
+ {Name: "open.example", TargetUrl: upstream.URL},
+ }); err != nil {
+ t.Fatal(err)
+ }
+
+ socketPath := filepath.Join(t.TempDir(), "node.sock")
+ srv, err := StartSidecarServer(node, "127.0.0.1:0", socketPath, "api-token", "", "", "")
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer func() { _ = srv.Close() }()
+ waitForSocket(t, socketPath)
+ base := "http://" + node.BoundHTTPAddr
+
+ do := func(t *testing.T, method, path string, headers map[string]string) *http.Response {
+ t.Helper()
+ req, err := http.NewRequest(method, base+path, nil)
+ if err != nil {
+ t.Fatal(err)
+ }
+ // The app sends the node's API token as its bearer, as it would send
+ // a provider key; the destination must never see it.
+ req.Header.Set("Authorization", "Bearer api-token")
+ for k, v := range headers {
+ req.Header.Set(k, v)
+ }
+ resp, err := (&http.Client{Timeout: 2 * time.Second}).Do(req)
+ if err != nil {
+ t.Fatal(err)
+ }
+ _ = resp.Body.Close()
+ return resp
+ }
+
+ // The node's own refusals name themselves, so an app can tell a policy
+ // denial from a 403 the destination sent.
+ proxyStatus := map[int]string{
+ http.StatusForbidden: "sam-node; error=http_request_denied",
+ http.StatusNotFound: "sam-node; error=destination_not_found",
+ }
+
+ tests := []struct {
+ name string
+ method string
+ path string
+ headers map[string]string
+ want int
+ }{
+ {"allowed method under the granted prefix", "GET", "/egress/api.github.com/repos/acme/dubbing/pulls?state=open", nil, http.StatusNoContent},
+ {"method outside the narrowed grant", "POST", "/egress/api.github.com/repos/acme/dubbing/pulls", nil, http.StatusForbidden},
+ {"path outside the narrowed grant", "GET", "/egress/api.github.com/user", nil, http.StatusForbidden},
+ {"local attenuation on path", "GET", "/egress/api.github.com/repos/acme/vault/keys", nil, http.StatusForbidden},
+ {"an agent inside the granted namespace", "GET", "/egress/api.github.com/repos/acme/x", map[string]string{api.HeaderSamAgent: "reviewer.acme.example"}, http.StatusNoContent},
+ {"an agent outside it", "GET", "/egress/api.github.com/repos/acme/x", map[string]string{api.HeaderSamAgent: "intruder.evil.example"}, http.StatusForbidden},
+ {"a destination with a plain grant takes any method", "DELETE", "/egress/open.example/anything", nil, http.StatusNoContent},
+ {"a destination not assigned to this node", "GET", "/egress/other.example/x", nil, http.StatusNotFound},
+ {"a mesh name is not an egress destination", "GET", "/egress/tools.mcp.sam.alt/x", nil, http.StatusNotFound},
+ }
+ decisions := func(destination, outcome string) float64 {
+ return counterValue(t, egressDecisionsTotal.WithLabelValues(destination, outcome))
+ }
+ before := map[[2]string]float64{}
+ for _, k := range [][2]string{{"api.github.com", egressOutcomeAllow}, {"api.github.com", egressOutcomeDeny}, {"open.example", egressOutcomeAllow}, {"other.example", egressOutcomeNotAssigned}} {
+ before[k] = decisions(k[0], k[1])
+ }
+
+ for _, tc := range tests {
+ t.Run(tc.name, func(t *testing.T) {
+ resp := do(t, tc.method, tc.path, tc.headers)
+ if resp.StatusCode != tc.want {
+ t.Errorf("%s %s: status %d, want %d", tc.method, tc.path, resp.StatusCode, tc.want)
+ }
+ if want, ok := proxyStatus[tc.want]; ok && resp.Header.Get("Proxy-Status") != want {
+ t.Errorf("%s %s: Proxy-Status %q, want %q", tc.method, tc.path, resp.Header.Get("Proxy-Status"), want)
+ }
+ if tc.want == http.StatusNoContent && resp.Header.Get("Proxy-Status") != "" {
+ t.Errorf("%s %s: an allowed request carries Proxy-Status %q", tc.method, tc.path, resp.Header.Get("Proxy-Status"))
+ }
+ })
+ }
+
+ // Every decision above is one increment of the decisions counter, by
+ // destination and outcome, so an operator can alert on denials and on
+ // requests for destinations nobody assigned.
+ for k, want := range map[[2]string]float64{
+ {"api.github.com", egressOutcomeAllow}: 2,
+ {"api.github.com", egressOutcomeDeny}: 4,
+ {"open.example", egressOutcomeAllow}: 1,
+ {"other.example", egressOutcomeNotAssigned}: 1,
+ } {
+ if got := decisions(k[0], k[1]) - before[k]; got != want {
+ t.Errorf("decisions{destination=%q,outcome=%q} moved by %v, want %v", k[0], k[1], got, want)
+ }
+ }
+
+ // Without the API token the gate refuses before anything is evaluated.
+ req, _ := http.NewRequest(http.MethodGet, base+"/egress/api.github.com/repos/acme/x", nil)
+ resp, err := (&http.Client{Timeout: 2 * time.Second}).Do(req)
+ if err != nil {
+ t.Fatal(err)
+ }
+ _ = resp.Body.Close()
+ if resp.StatusCode != http.StatusUnauthorized {
+ t.Errorf("untokened request: %d, want 401", resp.StatusCode)
+ }
+
+ // A dot segment never reaches the destination, however the mux and the
+ // handler split the work of refusing it.
+ if resp := do(t, http.MethodGet, "/egress/api.github.com/repos/acme/../../user", nil); resp.StatusCode == http.StatusNoContent {
+ t.Error("a traversal was forwarded")
+ }
+
+ // What the destination saw for the allowed requests.
+ if len(seen) == 0 {
+ t.Fatal("upstream saw no request")
+ }
+ for _, r := range seen {
+ if strings.Contains(r.URL.Path, "..") || r.URL.Path == "/user" {
+ t.Errorf("upstream saw a traversal: %s", r.URL.Path)
+ }
+ }
+ first := seen[0]
+ if first.URL.RequestURI() != "/repos/acme/dubbing/pulls?state=open" {
+ t.Errorf("upstream URI = %q", first.URL.RequestURI())
+ }
+ if first.Header.Get("Authorization") != "Bearer ghp_secret" {
+ t.Errorf("upstream Authorization = %q, want the node's credential", first.Header.Get("Authorization"))
+ }
+ for _, r := range seen {
+ for name := range r.Header {
+ if strings.HasPrefix(name, "X-Sam-") || strings.HasPrefix(name, "X-Forwarded-") || name == api.HeaderPeerID {
+ t.Errorf("upstream saw %s", name)
+ }
+ }
+ if strings.Contains(r.Header.Get("Authorization"), "api-token") {
+ t.Error("the client's API token reached the destination")
+ }
+ }
+}
diff --git a/internal/node/egress_test.go b/internal/node/egress_test.go
new file mode 100644
index 00000000..b46a1975
--- /dev/null
+++ b/internal/node/egress_test.go
@@ -0,0 +1,366 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package node
+
+import (
+ "context"
+ "crypto/ed25519"
+ "net/http"
+ "net/http/httptest"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+ "time"
+
+ "github.com/biscuit-auth/biscuit-go/v2"
+ "github.com/google/sam/api"
+ "github.com/libp2p/go-libp2p/core/peer"
+)
+
+// mintFor builds a token bound to peerID carrying facts, as the control plane
+// would, and returns it with the verifying key.
+func mintFor(t *testing.T, peerID peer.ID, facts ...biscuit.Fact) ([]byte, ed25519.PublicKey) {
+ t.Helper()
+ pub, priv, err := ed25519.GenerateKey(nil)
+ if err != nil {
+ t.Fatal(err)
+ }
+ builder := biscuit.NewBuilder(priv)
+ base := []biscuit.Fact{
+ {Predicate: biscuit.Predicate{Name: api.FactNode, IDs: []biscuit.Term{biscuit.String(peerID.String())}}},
+ {Predicate: biscuit.Predicate{Name: api.FactClientPeerID, IDs: []biscuit.Term{biscuit.String(peerID.String())}}},
+ {Predicate: biscuit.Predicate{Name: api.FactExpiration, IDs: []biscuit.Term{biscuit.Date(time.Now().Add(time.Hour))}}},
+ }
+ for _, f := range append(base, facts...) {
+ if err := builder.AddAuthorityFact(f); err != nil {
+ t.Fatal(err)
+ }
+ }
+ b, err := builder.Build()
+ if err != nil {
+ t.Fatal(err)
+ }
+ token, err := b.Serialize()
+ if err != nil {
+ t.Fatal(err)
+ }
+ return token, pub
+}
+
+// TestAuthorizeHTTPFacts pins that method(), path(), host() and port() are
+// injected from the RequestContext and decide both a narrowed grant and a
+// node's local attenuation, and that a request without HTTP facts does not
+// match a narrowed grant.
+func TestAuthorizeHTTPFacts(t *testing.T) {
+ dir := t.TempDir()
+ store, err := NewStore(dir)
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer func() { _ = store.Close() }()
+
+ caller := peer.ID("caller-peer")
+ narrowed := api.BuildHTTPGrantFacts(&api.HTTPGrant{
+ Service: "egress://api.github.com",
+ Methods: []string{"GET"},
+ Paths: []string{"/repos/acme/*"},
+ })
+ token, pub := mintFor(t, caller, append(narrowed, api.MarkerFact(api.FactTargetUnrestricted))...)
+
+ node := &SamNode{
+ Store: store,
+ trustedKeys: []TrustedKey{{Key: pub, ReceivedAt: time.Now()}},
+ BiscuitTimeout: 500 * time.Millisecond,
+ }
+ request := func(method, path string) RequestContext {
+ rc := RequestContext{PeerID: caller, Protocol: "/libp2p-http", Target: "egress://api.github.com",
+ Egress: &EgressFacts{Host: "api.github.com", Port: 443}}
+ if method != "" {
+ rc.HTTP = &HTTPRequestFacts{Method: method, Path: path}
+ }
+ return rc
+ }
+
+ if err := node.Authorize(token, request("GET", "/repos/acme/x"), pub); err != nil {
+ t.Errorf("GET under the granted prefix: %v", err)
+ }
+ if err := node.Authorize(token, request("POST", "/repos/acme/x"), pub); err == nil {
+ t.Error("POST was allowed on a GET-only grant")
+ }
+ if err := node.Authorize(token, request("GET", "/user"), pub); err == nil {
+ t.Error("a path outside the grant was allowed")
+ }
+ if err := node.Authorize(token, request("CONNECT", ""), pub); err == nil {
+ t.Error("a tunnel was allowed on a narrowed grant")
+ }
+ if err := node.Authorize(token, request("", ""), pub); err == nil {
+ t.Error("a request without HTTP facts was allowed on a narrowed grant")
+ }
+
+ // Local attenuation sees the same facts.
+ cfg, err := CompleteNodeConfig(api.NodeConfig{Attenuation: api.Attenuation{Policies: []string{
+ `deny if port($p), !($p == 443);`,
+ `deny if host("payroll.internal.example.com");`,
+ `deny if path($p), $p.starts_with("/repos/acme/secret");`,
+ }}})
+ if err != nil {
+ t.Fatal(err)
+ }
+ node.nodeConfig = cfg
+ if err := node.Authorize(token, request("GET", "/repos/acme/x"), pub); err != nil {
+ t.Errorf("attenuation denied a request it should not: %v", err)
+ }
+ if err := node.Authorize(token, request("GET", "/repos/acme/secret/1"), pub); err == nil {
+ t.Error("attenuation on path() did not fire")
+ }
+ rc := request("GET", "/repos/acme/x")
+ rc.Egress.Port = 8080
+ if err := node.Authorize(token, rc, pub); err == nil {
+ t.Error("attenuation on port() did not fire")
+ }
+}
+
+// TestAuthorizeLocalIsSelfTargeted: a node authorizing a local client's
+// request on its own credential passes the target check without a target
+// grant, and nothing else is relaxed.
+func TestAuthorizeLocalIsSelfTargeted(t *testing.T) {
+ dir := t.TempDir()
+ store, err := NewStore(dir)
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer func() { _ = store.Close() }()
+
+ self := peer.ID("self-peer")
+ grant := biscuit.Fact{Predicate: biscuit.Predicate{Name: api.FactGrantedServiceExact,
+ IDs: []biscuit.Term{biscuit.String("egress"), biscuit.String("api.github.com")}}}
+ token, pub := mintFor(t, self, grant)
+ node := &SamNode{Store: store, trustedKeys: []TrustedKey{{Key: pub, ReceivedAt: time.Now()}}, BiscuitTimeout: 500 * time.Millisecond}
+
+ local := RequestContext{PeerID: self, Protocol: "local-api", Target: "egress://api.github.com",
+ HTTP: &HTTPRequestFacts{Method: "GET", Path: "/"}, Local: true}
+ if err := node.Authorize(token, local, pub); err != nil {
+ t.Errorf("local request on own credential denied: %v", err)
+ }
+ remote := local
+ remote.Local = false
+ if err := node.Authorize(token, remote, pub); err == nil {
+ t.Error("the target check was skipped for a request that is not local")
+ }
+ other := local
+ other.Target = "egress://other.example"
+ if err := node.Authorize(token, other, pub); err == nil {
+ t.Error("Local relaxed the service grant")
+ }
+}
+
+// TestEgressServiceProxiesWithTheNodesCredential pins what the destination
+// sees: the node's credential from the secrets directory, none of the
+// caller's headers, the path as requested; and that a missing credential is
+// refused at Init.
+func TestEgressServiceProxiesWithTheNodesCredential(t *testing.T) {
+ var got *http.Request
+ upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ got = r.Clone(context.Background())
+ w.WriteHeader(http.StatusNoContent)
+ }))
+ defer upstream.Close()
+
+ secrets := t.TempDir()
+ if err := os.WriteFile(filepath.Join(secrets, "github-eu"), []byte("ghp_token\n"), 0o600); err != nil {
+ t.Fatal(err)
+ }
+ d := &api.EgressDestination{Name: "api.github.com", TargetUrl: upstream.URL, Credential: "github-eu"}
+ svc, err := newEgressService(d, secrets)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if err := svc.Init(context.Background()); err != nil {
+ t.Fatal(err)
+ }
+ if facts := egressFactsFor(svc); facts == nil || facts.Host != "api.github.com" || facts.Port != mustPort(t, upstream.URL) {
+ t.Errorf("egressFactsFor = %+v", facts)
+ }
+
+ req := httptest.NewRequest(http.MethodGet, "/repos/acme/x?state=open", nil)
+ req.Header.Set("Authorization", "Bearer the-callers-token")
+ req.Header.Set("Cookie", "session=the-callers-session")
+ req.Header.Set(api.HeaderSamAgent, "reviewer.acme.example")
+ req.Header.Set(api.HeaderPeerID, "12D3KooWCaller")
+ req.Header.Set("X-Forwarded-For", "10.0.0.1")
+ req.Header.Set("Accept", "application/json")
+ rr := httptest.NewRecorder()
+ svc.Handler().ServeHTTP(rr, req)
+ if rr.Code != http.StatusNoContent {
+ t.Fatalf("status %d: %s", rr.Code, rr.Body.String())
+ }
+ if got.Header.Get("Authorization") != "Bearer ghp_token" {
+ t.Errorf("upstream Authorization = %q, want the node's credential", got.Header.Get("Authorization"))
+ }
+ for _, h := range []string{"Cookie", api.HeaderSamAgent, api.HeaderPeerID, "X-Forwarded-For", "X-Forwarded-Host", "X-Forwarded-Proto"} {
+ if got.Header.Get(h) != "" {
+ t.Errorf("upstream saw %s=%q", h, got.Header.Get(h))
+ }
+ }
+ if got.Header.Get("Accept") != "application/json" {
+ t.Errorf("an ordinary header was dropped")
+ }
+ if got.URL.RequestURI() != "/repos/acme/x?state=open" {
+ t.Errorf("upstream path = %q", got.URL.RequestURI())
+ }
+
+ // Rotation by the platform applies without a restart.
+ if err := os.WriteFile(filepath.Join(secrets, "github-eu"), []byte("user:pass"), 0o600); err != nil {
+ t.Fatal(err)
+ }
+ svc.Handler().ServeHTTP(httptest.NewRecorder(), httptest.NewRequest(http.MethodGet, "/", nil))
+ if !strings.HasPrefix(got.Header.Get("Authorization"), "Basic ") {
+ t.Errorf("rotated credential not applied: %q", got.Header.Get("Authorization"))
+ }
+
+ // A credential that disappears after registration is a configuration
+ // error the client can tell from the destination's own answer.
+ if err := os.Remove(filepath.Join(secrets, "github-eu")); err != nil {
+ t.Fatal(err)
+ }
+ rr = httptest.NewRecorder()
+ svc.Handler().ServeHTTP(rr, httptest.NewRequest(http.MethodGet, "/", nil))
+ if rr.Code != http.StatusBadGateway || rr.Header().Get("Proxy-Status") != "sam-node; error=proxy_configuration_error" {
+ t.Errorf("missing credential at request time: %d %q", rr.Code, rr.Header().Get("Proxy-Status"))
+ }
+
+ // A credential the platform did not deliver is refused at Init.
+ missing, err := newEgressService(&api.EgressDestination{Name: "x.example", Credential: "absent"}, secrets)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if err := missing.Init(context.Background()); err == nil || !strings.Contains(err.Error(), "absent") {
+ t.Errorf("Init with a missing credential: %v", err)
+ }
+ // No credential named: the destination is reached anonymously.
+ anon, err := newEgressService(&api.EgressDestination{Name: "x.example", TargetUrl: upstream.URL}, secrets)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if err := anon.Init(context.Background()); err != nil {
+ t.Fatal(err)
+ }
+ anon.Handler().ServeHTTP(httptest.NewRecorder(), httptest.NewRequest(http.MethodGet, "/", nil))
+ if got.Header.Get("Authorization") != "" {
+ t.Errorf("anonymous destination received %q", got.Header.Get("Authorization"))
+ }
+}
+
+func mustPort(t *testing.T, rawURL string) int {
+ t.Helper()
+ svc, err := newEgressService(&api.EgressDestination{Name: "p.example", TargetUrl: rawURL}, t.TempDir())
+ if err != nil {
+ t.Fatal(err)
+ }
+ return svc.port()
+}
+
+// TestApplyEgressAssignmentsReconciles: assignments are registered, changed
+// ones replaced, withdrawn ones unregistered, and one broken assignment does
+// not stop the others.
+func TestApplyEgressAssignmentsReconciles(t *testing.T) {
+ secrets := t.TempDir()
+ if err := os.WriteFile(filepath.Join(secrets, "cred"), []byte("tok"), 0o600); err != nil {
+ t.Fatal(err)
+ }
+ node := &SamNode{services: NewServiceRegistry(&fakeDHT{}, time.Second), config: Options{SecretsDir: secrets}}
+ ctx := context.Background()
+ assignments := func(outcome string) float64 {
+ return counterValue(t, egressAssignmentsTotal.WithLabelValues(outcome))
+ }
+ registeredBefore, withdrawnBefore, refusedBefore := assignments("registered"), assignments("withdrawn"), assignments("refused")
+
+ err := node.applyEgressAssignments(ctx, []*api.EgressDestination{
+ {Name: "a.example", Credential: "cred"},
+ {Name: "b.example"},
+ {Name: "broken.example", Credential: "missing"},
+ })
+ if err == nil || !strings.Contains(err.Error(), "missing") {
+ t.Fatalf("expected the broken assignment to be reported, got %v", err)
+ }
+ if names := egressNames(node); !equalStrings(names, []string{"a.example", "b.example"}) {
+ t.Fatalf("registered %v", names)
+ }
+ if got := assignments("registered") - registeredBefore; got != 2 {
+ t.Errorf("registered counter moved by %v, want 2", got)
+ }
+ if got := assignments("refused") - refusedBefore; got != 1 {
+ t.Errorf("refused counter moved by %v, want 1", got)
+ }
+
+ // b changes its target, a is withdrawn, c appears.
+ if err := node.applyEgressAssignments(ctx, []*api.EgressDestination{
+ {Name: "b.example", TargetUrl: "http://b.internal:8080"},
+ {Name: "c.example"},
+ }); err != nil {
+ t.Fatal(err)
+ }
+ if names := egressNames(node); !equalStrings(names, []string{"b.example", "c.example"}) {
+ t.Fatalf("registered %v", names)
+ }
+ b, _ := node.services.GetTyped(api.ServiceType_SERVICE_TYPE_EGRESS, "b.example")
+ if facts := egressFactsFor(b); facts.Port != 8080 {
+ t.Errorf("b was not replaced: %+v", facts)
+ }
+ if got := assignments("withdrawn") - withdrawnBefore; got != 1 {
+ t.Errorf("withdrawn counter moved by %v, want 1", got)
+ }
+}
+
+func egressNames(node *SamNode) []string {
+ var names []string
+ for _, info := range node.services.List(api.ServiceType_SERVICE_TYPE_EGRESS) {
+ names = append(names, info.GetName())
+ }
+ return names
+}
+
+func equalStrings(got, want []string) bool {
+ if len(got) != len(want) {
+ return false
+ }
+ seen := map[string]bool{}
+ for _, g := range got {
+ seen[g] = true
+ }
+ for _, w := range want {
+ if !seen[w] {
+ return false
+ }
+ }
+ return true
+}
+
+// TestNodeConfigRefusesEgressServices: a destination is the control plane's
+// to assign, so the node config cannot declare one.
+func TestNodeConfigRefusesEgressServices(t *testing.T) {
+ _, err := CompleteNodeConfig(api.NodeConfig{Services: []api.ServiceConfig{{Type: "egress", Name: "api.github.com", TargetURL: "https://api.github.com"}}})
+ if err == nil || !strings.Contains(err.Error(), "assigned by the control plane") {
+ t.Fatalf("CompleteNodeConfig accepted an egress service: %v", err)
+ }
+ _, err = NewServiceFromRequest(&api.RegisterServiceRequest{
+ Service: &api.ServiceInfo{Type: api.ServiceType_SERVICE_TYPE_EGRESS, Name: "api.github.com"},
+ Backend: &api.RegisterServiceRequest_TargetUrl{TargetUrl: "https://api.github.com"},
+ })
+ if err == nil || !strings.Contains(err.Error(), "assigned by the control plane") {
+ t.Fatalf("NewServiceFromRequest accepted an egress service: %v", err)
+ }
+}
diff --git a/internal/node/middleware.go b/internal/node/middleware.go
index 435953c1..2d627df5 100644
--- a/internal/node/middleware.go
+++ b/internal/node/middleware.go
@@ -50,6 +50,35 @@ type RequestContext struct {
// So it is attribution, not proof. Policy that cares should also constrain
// which peers may speak for which agent namespaces.
Agent string
+
+ // HTTP is set when the node handles the request as HTTP: the method as
+ // received and the path as the backend sees it. Injected as method() and
+ // path() facts, taken from the wire and never from the caller's token. A
+ // tunnel the node opens without terminating HTTP carries Method "CONNECT"
+ // and an empty Path. Nil on a stream that carries no HTTP request.
+ HTTP *HTTPRequestFacts
+
+ // Egress is set on a request for an egress destination: the hostname and
+ // port the node connects to, injected as host() and port() facts.
+ Egress *EgressFacts
+
+ // Local marks a request this node makes for one of its own clients over the
+ // local API, for a destination it serves itself. The caller is then this
+ // node, evaluated on its own credential, and the target check is satisfied
+ // because a node is always allowed to reach itself. Never set from the wire.
+ Local bool
+}
+
+// HTTPRequestFacts is what an HTTP request contributes to policy.
+type HTTPRequestFacts struct {
+ Method string
+ Path string
+}
+
+// EgressFacts is the destination of an egress request.
+type EgressFacts struct {
+ Host string
+ Port int
}
// recoverStreamHandler isolates a panic while processing untrusted peer bytes
@@ -280,6 +309,33 @@ func (n *SamNode) Authorize(rawToken []byte, req RequestContext, pubKey ed25519.
// Enforce client_peer_id matches connection_peer_id
authorizer.AddCheck(api.BaselineReplayCheck)
+ // The request as the wire carried it. Present only when there is an HTTP
+ // request, so a grant narrowed to methods and paths (PolicyRole.http) has
+ // nothing to match on a bare stream and fails closed.
+ if req.HTTP != nil {
+ authorizer.AddFact(biscuit.Fact{Predicate: biscuit.Predicate{
+ Name: api.FactMethod,
+ IDs: []biscuit.Term{biscuit.String(req.HTTP.Method)},
+ }})
+ authorizer.AddFact(biscuit.Fact{Predicate: biscuit.Predicate{
+ Name: api.FactPath,
+ IDs: []biscuit.Term{biscuit.String(req.HTTP.Path)},
+ }})
+ }
+ if req.Egress != nil {
+ authorizer.AddFact(biscuit.Fact{Predicate: biscuit.Predicate{
+ Name: api.FactHost,
+ IDs: []biscuit.Term{biscuit.String(req.Egress.Host)},
+ }})
+ authorizer.AddFact(biscuit.Fact{Predicate: biscuit.Predicate{
+ Name: api.FactPort,
+ IDs: []biscuit.Term{biscuit.Integer(req.Egress.Port)},
+ }})
+ }
+ if req.Local {
+ authorizer.AddFact(api.MarkerFact(api.FactTargetUnrestricted))
+ }
+
identity.EnforceExpiration(authorizer)
// Inject facts from our own identity token to support target matching
@@ -307,6 +363,9 @@ func (n *SamNode) Authorize(rawToken []byte, req RequestContext, pubKey ed25519.
for _, r := range api.BaselineRules {
authorizer.AddRule(r)
}
+ for _, r := range api.BaselineHTTPRules {
+ authorizer.AddRule(r)
+ }
// Apply Dynamic Mesh Policy Rules
n.MeshPolicyMu.RLock()
@@ -319,7 +378,8 @@ func (n *SamNode) Authorize(rawToken []byte, req RequestContext, pubKey ed25519.
err = authorizer.Authorize()
if err != nil {
- logger.Errorf("Authorizer failure: %v, token: %s", err, b.String())
+ logger.Infow("Audit Traceability", append(req.auditFields(), "decision", "deny", "reason", err.Error())...)
+ logger.Debugf("Authorizer failure: %v, token: %s", err, b.String())
logger.Debugf("Authorizer state: %s", authorizer.PrintWorld())
return err
}
@@ -353,18 +413,37 @@ func (n *SamNode) Authorize(rawToken []byte, req RequestContext, pubKey ed25519.
}
}
- logger.Infow("Audit Traceability",
- "peer_id", req.PeerID.String(),
+ logger.Infow("Audit Traceability", append(req.auditFields(),
+ "decision", "allow",
"user", userStr,
"email", emailStr,
"role", roleStr,
- "target", req.Target,
- "protocol", req.Protocol,
- )
+ )...)
return nil
}
+// auditFields is what every authorization decision logs about the request:
+// who asked, for what, and the request facts policy saw. One line per
+// decision, allow or deny, is the audit trail of the PEP.
+func (req RequestContext) auditFields() []any {
+ fields := []any{
+ "peer_id", req.PeerID.String(),
+ "target", req.Target,
+ "protocol", req.Protocol,
+ }
+ if req.Agent != "" {
+ fields = append(fields, "agent", req.Agent)
+ }
+ if req.HTTP != nil {
+ fields = append(fields, "method", req.HTTP.Method, "path", req.HTTP.Path)
+ }
+ if req.Egress != nil {
+ fields = append(fields, "host", req.Egress.Host, "port", req.Egress.Port)
+ }
+ return fields
+}
+
func (n *SamNode) injectIdentityFacts(authorizer biscuit.Authorizer, pubKey ed25519.PublicKey) error {
ourIdentity := n.GetIdentity()
if ourIdentity == nil {
diff --git a/internal/node/node.go b/internal/node/node.go
index 7ef2d962..c8d8398b 100644
--- a/internal/node/node.go
+++ b/internal/node/node.go
@@ -172,7 +172,11 @@ type SamNode struct {
keysMu sync.RWMutex
MeshPolicyRules []biscuit.Rule
MeshPolicyMu sync.RWMutex
- rateLimiter *ratelimit.PeerRateLimiter
+ // pendingEgress holds assignments that arrived before Start created the
+ // service registry (SyncControlPlane runs first); Start applies them.
+ pendingEgress []*api.EgressDestination
+ pendingEgressMu sync.Mutex
+ rateLimiter *ratelimit.PeerRateLimiter
// handshakeLimiter bounds /sam/auth attempts per peer separately from
// rateLimiter, so a peer's authenticated traffic cannot starve its own
// re-authentication and vice versa.
@@ -567,6 +571,7 @@ func (n *SamNode) Start(ctx context.Context) error {
n.services = NewServiceRegistry(n.DHT, n.config.BackendProbeTimeout)
n.services.reprovideNow = n.triggerReprovide
+ n.applyPendingEgress(ctx)
var authenticated bool
var fatalAuthErr error
@@ -2168,14 +2173,28 @@ func (n *SamNode) StartIngressServer(ctx context.Context) error {
Protocol: "/libp2p-http",
Target: target,
Agent: agentClaim(r.Header.Get(api.HeaderSamAgent)),
+ // The path policy sees is the one the backend will see, decided
+ // here so it can never be the routing prefix.
+ HTTP: &HTTPRequestFacts{Method: r.Method, Path: "/" + upstreamPath},
+ }
+ if serviceType == api.ServiceType_SERVICE_TYPE_EGRESS {
+ if svc, ok := n.services.GetTyped(serviceType, serviceName); ok {
+ reqCtx.Egress = egressFactsFor(svc)
+ }
}
// Verify authorization
if err := n.VerifyBiscuitToken(biscuitBytes, reqCtx); err != nil {
logger.Warnf("[Ingress] AuthZ Denied for %s: %v", remotePeer, err)
- http.Error(w, "Authorization failed", http.StatusForbidden)
+ if serviceType == api.ServiceType_SERVICE_TYPE_EGRESS {
+ recordEgressDecision(serviceName, egressOutcomeDeny)
+ }
+ refuse(w, http.StatusForbidden, "Authorization failed", proxyStatusDenied)
return
}
+ if serviceType == api.ServiceType_SERVICE_TYPE_EGRESS {
+ recordEgressDecision(serviceName, egressOutcomeAllow)
+ }
// Strip the biscuit header so it doesn't leak to the backend service
r.Header.Del(api.HeaderSamBiscuit)
diff --git a/internal/node/options.go b/internal/node/options.go
index ed19fee8..d67eeb52 100644
--- a/internal/node/options.go
+++ b/internal/node/options.go
@@ -87,6 +87,10 @@ type Options struct {
// is tight enough that even simple interpreted-language MCP servers can
// miss it on first spawn.
BackendProbeTimeout time.Duration
+ // SecretsDir is where the node resolves the credential names the control
+ // plane assigns with egress destinations: one file per name, put there by
+ // the platform (a Secret volume, a vault agent). Zero uses DefaultSecretsDir.
+ SecretsDir string
// CatalogReportInterval specifies how often the node self-reports its
// locally registered services to the control plane (POST
// /nodes/catalog), so an admin can see mesh-wide service topology
@@ -147,6 +151,9 @@ func (o *Options) Default() {
if o.ControlPlaneSyncInterval == 0 {
o.ControlPlaneSyncInterval = DefaultControlPlaneSyncInterval
}
+ if o.SecretsDir == "" {
+ o.SecretsDir = DefaultSecretsDir
+ }
if o.CatalogReportInterval <= 0 {
o.CatalogReportInterval = 1 * time.Minute
}
diff --git a/internal/node/service.go b/internal/node/service.go
index d167579d..321b166a 100644
--- a/internal/node/service.go
+++ b/internal/node/service.go
@@ -130,6 +130,8 @@ func NewServiceFromRequest(req *api.RegisterServiceRequest) (Service, error) {
return &InferenceService{baseService: baseService{info: info, backend: req.Backend}}, nil
case api.ServiceType_SERVICE_TYPE_A2A:
return &A2AService{baseService: baseService{info: info, backend: req.Backend}}, nil
+ case api.ServiceType_SERVICE_TYPE_EGRESS:
+ return nil, fmt.Errorf("service %q: egress destinations are assigned by the control plane (PolicyConfig.egress), not registered on a node", info.GetName())
default:
return nil, fmt.Errorf("unspecified or unsupported service type: %v", info.Type)
}
diff --git a/internal/node/sidecar.go b/internal/node/sidecar.go
index 2453083f..0cf6338b 100644
--- a/internal/node/sidecar.go
+++ b/internal/node/sidecar.go
@@ -93,6 +93,15 @@ func StartSidecarServer(node *SamNode, addr, socketPath, token, certFile, keyFil
mux.Handle("/v1/chat/completions", withAuth(token, true, withMeshConnection(node, http.HandlerFunc(facade.handleCompletions))))
mux.Handle("/v1/completions", withAuth(token, true, withMeshConnection(node, http.HandlerFunc(facade.handleCompletions))))
+ // Egress destinations this node serves, for local clients. Same gate as
+ // the facade: an SDK sends the sidecar token as its api_key. Whatever
+ // Authorization survives the gate is dropped by the egress handler, which
+ // presents the node's own credential to the destination. Not behind
+ // withMeshConnection: the destination is outside the mesh.
+ mux.Handle("/egress/", withAuth(token, true, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ handleLocalEgress(node, w, r)
+ })))
+
// Mount MCP handler
mcpHandler := NewMCPHandler(node)
mux.Handle("/", withAuth(token, true, withMeshConnection(node, mcpHandler)))
diff --git a/internal/sambox/route.go b/internal/sambox/route.go
index 82087dcb..f6582d7e 100644
--- a/internal/sambox/route.go
+++ b/internal/sambox/route.go
@@ -127,6 +127,17 @@ func (p *EgressPolicy) Allows(host string) bool {
return false
}
+// AllowsLiteral reports whether an address the guest dialled without ever
+// resolving a name may be reached. Only an exact entry can say so: a
+// wildcard names a DNS zone, and an address is in no zone.
+func (p *EgressPolicy) AllowsLiteral(addr string) bool {
+ if p == nil {
+ return false
+ }
+ _, ok := p.exact[api.NormalizeMeshHost(addr)]
+ return ok
+}
+
// Router classifies destinations arriving on the sandbox boundary.
type Router struct {
// Egress is the allowlist for destinations outside the mesh. Nil denies
@@ -159,10 +170,17 @@ func (r *Router) Route(dst Destination) (Route, error) {
return Route{Kind: RouteMeshService, ServiceURI: serviceURI, Destination: dst}, nil
}
- // Literal addresses are not special-cased: they carry no name, so they are
- // allowed only by an exact entry. CIDR ranges are deliberately not
- // supported yet; adding them is a policy-language decision, not a routing
- // one.
+ // An address carries no name. The guest stack forwards one when a flow
+ // was opened to an address it never resolved, so policy has nothing to
+ // decide on but the address itself: only an exact entry allows it. CIDR
+ // ranges are deliberately not supported; adding them is a policy-language
+ // decision, not a routing one.
+ if !dst.IsName {
+ if !r.Egress.AllowsLiteral(dst.Name) {
+ return Route{}, fmt.Errorf("%w: %s is an address, not a name", ErrNotAllowed, dst.Name)
+ }
+ return Route{Kind: RouteExternal, Destination: dst}, nil
+ }
if !r.Egress.Allows(dst.Name) {
return Route{}, fmt.Errorf("%w: %s", ErrNotAllowed, dst.Name)
}
diff --git a/internal/sambox/route_test.go b/internal/sambox/route_test.go
index c18a67dc..abe2c96d 100644
--- a/internal/sambox/route_test.go
+++ b/internal/sambox/route_test.go
@@ -91,6 +91,35 @@ func TestRouteClassification(t *testing.T) {
// TestMeshNamesIgnoreEgressPolicy pins that mesh routing is not reachable
// through the allowlist: a mesh name is authorized by mesh policy, and an
// operator listing it under egress must not change how it is routed.
+// TestLiteralAddressesNeedAnExactEntry: the guest stack forwards an address
+// when a flow was opened to one it never resolved. Policy is written on
+// names, so a wildcard cannot cover it; only an exact entry does, and with no
+// policy at all it is denied like everything else.
+func TestLiteralAddressesNeedAnExactEntry(t *testing.T) {
+ policy, err := NewEgressPolicy([]string{"*.3.4", "198.51.100.7", "api.github.com"})
+ if err != nil {
+ t.Fatalf("NewEgressPolicy: %v", err)
+ }
+ r := &Router{Egress: policy}
+
+ for _, addr := range []string{"1.2.3.4", "2001:db8::1", "10.0.0.1"} {
+ if _, err := r.Route(Destination{Name: addr, Port: 443, IsName: false}); !errors.Is(err, ErrNotAllowed) {
+ t.Errorf("Route(%q as address) = %v, want ErrNotAllowed", addr, err)
+ }
+ }
+ got, err := r.Route(Destination{Name: "198.51.100.7", Port: 5432, IsName: false})
+ if err != nil || got.Kind != RouteExternal {
+ t.Errorf("an exactly listed address = %+v, %v; want RouteExternal", got, err)
+ }
+ // The same string as a name is still matched as a name.
+ if _, err := r.Route(Destination{Name: "x.3.4", Port: 443, IsName: true}); err != nil {
+ t.Errorf("a name under the wildcard: %v", err)
+ }
+ if _, err := (&Router{}).Route(Destination{Name: "198.51.100.7", Port: 443, IsName: false}); !errors.Is(err, ErrNotAllowed) {
+ t.Errorf("an address with no policy = %v, want ErrNotAllowed", err)
+ }
+}
+
func TestMeshNamesIgnoreEgressPolicy(t *testing.T) {
policy, err := NewEgressPolicy([]string{"*.sam.alt"})
if err != nil {