diff --git a/README.md b/README.md index f342e35..6ec4e5b 100644 --- a/README.md +++ b/README.md @@ -247,6 +247,8 @@ A call is ` http:////` with header `X-Keyring-Tok - does not count a call against the daily limit if the service was unreachable; - writes one audit line per call, with no keys, tokens, query strings or bodies. The audit log, like the store, is refused if other users can read it. +**Naming the caller to a service you run.** With `"forward_role": true` on a service, every call carries `X-Keyring-Role: `, so a service the fleet runs itself (a build server, for example) can log which agent sent a call; through a relay all callers otherwise look the same. It is off by default (third-party APIs get no role names) and refused for services that forward nothing (signing, `gcloud-login`, `egress-proxy`). The keyring drops a caller-sent `X-Keyring-Role` on every call, so the header cannot be forged through it; anything that reaches the service without the keyring can still send one. Set it in `access.json` or with pasted settings when connecting or editing; the service page shows it. + A service that echoes a key in some other encoding (for example base64 inside a larger text) is not protected; do not route such a service through the keyring. Allowed methods default to GET, HEAD and POST. A role's `"expires"` ends all its access (401); an access's own `"expires"` (RFC 3339, like `"2026-12-31T00:00:00Z"`) ends only that service (403). diff --git a/internal/dashboard/dashboard.go b/internal/dashboard/dashboard.go index e60a016..b6dfff0 100644 --- a/internal/dashboard/dashboard.go +++ b/internal/dashboard/dashboard.go @@ -849,6 +849,7 @@ type connectForm struct { KeyPart string PartHeaders map[string]string OAuth2 *policy.OAuth2 + ForwardRole bool } // agentSettings is what an agent may hand the owner to paste: the same @@ -863,6 +864,8 @@ type agentSettings struct { TLSPin string `json:"tls_pin_sha256,omitempty"` FixedHeaders map[string]string `json:"fixed_headers,omitempty"` Project string `json:"project,omitempty"` + // ForwardRole sends the calling agent's name upstream (X-Keyring-Role). + ForwardRole bool `json:"forward_role,omitempty"` // ExtraHeaders sends more secret values with each call: header name -> // name of another stored key, never a value. A pointer, so an edit can // tell "left out" (keep) from {} (remove). @@ -983,7 +986,7 @@ func (b *Backend) connectKey(w http.ResponseWriter, r *http.Request, sid string) return } f.Service, f.Base, f.Auth, f.Header, f.Param, f.TestPath, f.TLSPin = a.Service, a.Base, a.Auth, a.Header, a.Param, a.TestPath, a.TLSPin - f.FixedHeaders, f.Project = a.FixedHeaders, a.Project + f.FixedHeaders, f.Project, f.ForwardRole = a.FixedHeaders, a.Project, a.ForwardRole if a.ExtraHeaders != nil { f.ExtraHeaders = *a.ExtraHeaders } @@ -1068,7 +1071,7 @@ func (b *Backend) connectKey(w http.ResponseWriter, r *http.Request, sid string) if len(f.ExtraHeaders) > 0 { extra = f.ExtraHeaders } - next.Services[f.Service] = policy.Service{Base: f.Base, Key: keyName, Auth: f.Auth, Header: f.Header, Param: f.Param, TestPath: f.TestPath, TLSPinSHA256: f.TLSPin, FixedHeaders: f.FixedHeaders, ExtraHeaders: extra, Project: f.Project, APNs: f.APNs, SignInWithApple: f.SignInWithApple, OAuth2: f.OAuth2} + next.Services[f.Service] = policy.Service{Base: f.Base, Key: keyName, Auth: f.Auth, Header: f.Header, Param: f.Param, TestPath: f.TestPath, TLSPinSHA256: f.TLSPin, FixedHeaders: f.FixedHeaders, ExtraHeaders: extra, Project: f.Project, ForwardRole: f.ForwardRole, APNs: f.APNs, SignInWithApple: f.SignInWithApple, OAuth2: f.OAuth2} if err := (&policy.Config{Rules: b.rules(), AccessList: next}).Validate(); err != nil { again(http.StatusBadRequest, err.Error()) return diff --git a/internal/dashboard/pages.go b/internal/dashboard/pages.go index 9a2a443..45e4b97 100644 --- a/internal/dashboard/pages.go +++ b/internal/dashboard/pages.go @@ -279,6 +279,7 @@ Sign in with Apple: {"service":"NAME","auth":"sign-in-with-apple-sign","si
Agents
{{range .Agents}}{{.}}{{else}}none{{end}}
{{if .F.FixedHeaders}}
Fixed headers
{{range $k, $v := .F.FixedHeaders}}{{$k}}: {{$v}}
{{end}}
{{end}} {{with .OAuth2}}
OAuth client ID
{{.ClientID}}
Token URL
{{.TokenURL}}
{{if .ClientSecretKey}}
Client secret
{{.ClientSecretKey}}{{if not $.SecretStored}} (no value stored){{end}}
{{end}}{{with .Scopes}}
Scopes
{{range .}}{{.}}
{{end}}
{{end}}{{end}} +{{if .F.ForwardRole}}
Agent name
sent as X-Keyring-Role
{{end}} {{if .F.ExtraHeaders}}
Extra secret headers
{{range .F.ExtraHeaders}}{{.}}
{{end}}
{{end}} {{if .Editable}} diff --git a/internal/dashboard/services.go b/internal/dashboard/services.go index b5e2ca4..260c58c 100644 --- a/internal/dashboard/services.go +++ b/internal/dashboard/services.go @@ -49,11 +49,13 @@ type serviceForm struct { // OAuth client settings of an oauth2 service (#142): the secret is a key // name, never a value. ClientID, TokenURL, ClientSecretKey string + // ForwardRole is shown, and changed only by pasting settings. + ForwardRole bool } func formOf(name string, svc policy.Service) serviceForm { f := serviceForm{Name: name, Key: svc.Key, Base: svc.Base, Auth: svc.Auth, Header: svc.Header, Param: svc.Param, - TestPath: svc.TestPath, TLSPin: svc.TLSPinSHA256, Project: svc.Project, FixedHeaders: svc.FixedHeaders} + TestPath: svc.TestPath, TLSPin: svc.TLSPinSHA256, Project: svc.Project, FixedHeaders: svc.FixedHeaders, ForwardRole: svc.ForwardRole} if o := svc.OAuth2; o != nil { f.ClientID, f.TokenURL, f.ClientSecretKey = o.ClientID, o.TokenURL, o.ClientSecretKey } @@ -151,6 +153,7 @@ func (b *Backend) saveService(w http.ResponseWriter, r *http.Request, sid string } pasted := f.Pasted != "" var fixed map[string]string + var forwardRole bool var extra *map[string]string // nil: keep the stored extra headers var oauth *policy.OAuth2 // pasted: replaces the OAuth settings if pasted { @@ -172,7 +175,7 @@ func (b *Backend) saveService(w http.ResponseWriter, r *http.Request, sid string return } f.Base, f.Auth, f.Header, f.Param, f.TestPath, f.TLSPin, f.Project = a.Base, a.Auth, a.Header, a.Param, a.TestPath, a.TLSPin, a.Project - fixed, extra, oauth = a.FixedHeaders, a.ExtraHeaders, a.OAuth2 + fixed, extra, oauth, forwardRole = a.FixedHeaders, a.ExtraHeaders, a.OAuth2, a.ForwardRole } b.Mu.Lock() defer b.Mu.Unlock() @@ -214,7 +217,7 @@ func (b *Backend) saveService(w http.ResponseWriter, r *http.Request, sid string updated.Base, updated.Key, updated.Auth, updated.Header, updated.Param = f.Base, f.Key, f.Auth, f.Header, f.Param updated.TestPath, updated.TLSPinSHA256, updated.Project = f.TestPath, f.TLSPin, f.Project if pasted { - updated.FixedHeaders = fixed + updated.FixedHeaders, updated.ForwardRole = fixed, forwardRole } if cur.Auth == policy.AuthOAuth2 { next := *cur.OAuth2 @@ -309,7 +312,7 @@ func changedFields(old, now policy.Service) []string { }{ {"base", old.Base != now.Base}, {"key", old.Key != now.Key}, {"auth", old.Auth != now.Auth}, {"header", old.Header != now.Header}, {"param", old.Param != now.Param}, {"test_path", old.TestPath != now.TestPath}, - {"tls_pin_sha256", old.TLSPinSHA256 != now.TLSPinSHA256}, {"project", old.Project != now.Project}, {"fixed_headers", !maps.Equal(old.FixedHeaders, now.FixedHeaders)}, + {"tls_pin_sha256", old.TLSPinSHA256 != now.TLSPinSHA256}, {"project", old.Project != now.Project}, {"fixed_headers", !maps.Equal(old.FixedHeaders, now.FixedHeaders)}, {"forward_role", old.ForwardRole != now.ForwardRole}, {"extra_headers", !maps.Equal(old.ExtraHeaders, now.ExtraHeaders)}, {"oauth2", !old.OAuth2.Equal(now.OAuth2)}, } { diff --git a/internal/dashboard/services_test.go b/internal/dashboard/services_test.go index 899e5d7..b163d54 100644 --- a/internal/dashboard/services_test.go +++ b/internal/dashboard/services_test.go @@ -299,3 +299,24 @@ func TestServiceProjectFromTheDashboard(t *testing.T) { t.Fatal("a call to a service in a paused project was not refused") } } + +// Jarvis 488215: forward_role is set by pasted settings, survives a plain +// form edit, shows on the service page, and its change is audited. +func TestForwardRoleSetByPasteKeptByFormEdit(t *testing.T) { + e := newEnv(t) + base := e.proxy.Config().Services["api"].Base + w := e.edit("api", url.Values{"pasted": {`{"base":"` + base + `","auth":"bearer","forward_role":true}`}}) + if w.Header().Get("Location") != "/services/api?done=saved" || !e.proxy.Config().Services["api"].ForwardRole { + t.Fatalf("paste with forward_role: %d %s", w.Code, w.Body.String()) + } + if !strings.Contains(e.audit.String(), `"forward_role"`) { + t.Fatalf("audit does not name the change: %s", e.audit.String()) + } + if !strings.Contains(e.request("GET", "/services/api", nil).Body.String(), "X-Keyring-Role") { + t.Fatal("service page does not show that the agent's name is sent") + } + w = e.edit("api", url.Values{"key": {"API_KEY"}, "base": {base}, "auth": {"bearer"}, "test_path": {"/ping"}}) + if w.Header().Get("Location") != "/services/api?done=saved" || !e.proxy.Config().Services["api"].ForwardRole { + t.Fatalf("a form edit dropped forward_role: %d", w.Code) + } +} diff --git a/internal/policy/policy.go b/internal/policy/policy.go index 772667e..8bc57aa 100644 --- a/internal/policy/policy.go +++ b/internal/policy/policy.go @@ -321,10 +321,20 @@ type Service struct { Minisign *Minisign `json:"minisign,omitempty"` // APNs fixes the public identity of an APNs auth key (auth apns). APNs *APNs `json:"apns,omitempty"` + // ForwardRole sends the calling role's name upstream in RoleHeader, so + // a service the fleet runs itself can tell callers apart (Jarvis + // 488215: macserve saw every relay caller as the same client). Off by + // default: a third-party API has no use for role names. + ForwardRole bool `json:"forward_role,omitempty"` base *url.URL } +// RoleHeader carries the calling role's name to a service with ForwardRole. +// The keyring drops any caller-sent copy on every call, so it cannot be +// forged through the keyring. +const RoleHeader = "X-Keyring-Role" + // AppleAds fixes the public identity of the Apple Ads client secret. type AppleAds struct { ClientID string `json:"client_id"` @@ -1067,6 +1077,9 @@ func (s *Service) validate() error { seenHeaders[name], seenKeys[key] = true, true } } + if s.ForwardRole && (s.SignOnly() || s.Auth == AuthGcloudLogin || s.Auth == AuthEgressProxy) { + return errors.New("forward_role needs a service that forwards calls") + } if s.Minisign != nil && s.Auth != AuthMinisignSign { return errors.New("minisign settings require auth minisign-sign") } diff --git a/internal/server/server.go b/internal/server/server.go index 77622c2..011a54f 100644 --- a/internal/server/server.go +++ b/internal/server/server.go @@ -669,6 +669,9 @@ func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) { if callerUploadToken != "" { sendKey = callerUploadToken } + if svc.ForwardRole { + header.Set(policy.RoleHeader, roleName) + } out, err := buildOutbound(r.Context(), svc, sendKey, r.Method, rest, r.URL.RawQuery, header, r.Body, r.ContentLength) if errors.Is(err, errBadQuery) { h.refund(roleName, service, access.DailyRequests, start) @@ -968,6 +971,7 @@ func outboundHeader(in http.Header, svc policy.Service) http.Header { out.Del(name) } out.Del(TokenHeader) + out.Del(policy.RoleHeader) out.Del(workspace.GenerationHeader) out.Del("Authorization") out.Del("Cookie") diff --git a/internal/server/server_test.go b/internal/server/server_test.go index 6c4cbca..dda1687 100644 --- a/internal/server/server_test.go +++ b/internal/server/server_test.go @@ -732,3 +732,38 @@ func TestRestoreDailyCountsNeverGivesMoreCalls(t *testing.T) { t.Fatalf("next day: %d", w.Code) } } + +// Jarvis 488215: a service with forward_role learns which role called it; +// a caller cannot forge the header, and services without it never see one. +func TestForwardRoleNamesTheCallerAndCannotBeForged(t *testing.T) { + up, got := upstream(t) + on := bearer + on.ForwardRole = true + h, _ := newHandler(t, up.URL, on, allowAll) + if w := call(h, "POST", "/api/v1/jobs/j1/cancel", testToken, map[string]string{"x-keyring-role": "owner"}); w.Code != http.StatusOK { + t.Fatalf("status %d", w.Code) + } + if v := got.last(t).Header.Values(policy.RoleHeader); len(v) != 1 || v[0] != "phobos" { + t.Fatalf("upstream role header = %q, want [phobos]", v) + } + h, _ = newHandler(t, up.URL, bearer, allowAll) + call(h, "GET", "/api/v1/x", testToken, map[string]string{policy.RoleHeader: "owner"}) + if v := got.last(t).Header.Values(policy.RoleHeader); len(v) != 0 { + t.Fatalf("service without forward_role got %q", v) + } + for _, svc := range []string{ + `{"auth":"minisign-sign","key":"K"}`, + `{"auth":"egress-proxy","key":"K"}`, + } { + var s policy.Service + if err := json.Unmarshal([]byte(svc), &s); err != nil { + t.Fatal(err) + } + s.ForwardRole = true + cfg := &policy.Config{Rules: policy.Rules{Listen: "127.0.0.1:7701", AllowSources: []string{caller}, AuditLog: "audit.log"}, + AccessList: policy.AccessList{Services: map[string]policy.Service{"x": s}}} + if err := cfg.Validate(); err == nil || !strings.Contains(err.Error(), "forward_role") { + t.Errorf("%s with forward_role: %v", svc, err) + } + } +}