Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -247,6 +247,8 @@ A call is `<METHOD> http://<listen>/<service>/<path>` 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: <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).
Expand Down
7 changes: 5 additions & 2 deletions internal/dashboard/dashboard.go
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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).
Expand Down Expand Up @@ -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
}
Expand Down Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions internal/dashboard/pages.go
Original file line number Diff line number Diff line change
Expand Up @@ -279,6 +279,7 @@ Sign in with Apple: <code>{"service":"NAME","auth":"sign-in-with-apple-sign","si
<dt>Agents</dt><dd>{{range .Agents}}<a class="chip" href="/access/{{.}}/{{$.Name}}">{{.}}</a>{{else}}<span class="mute">none</span>{{end}}</dd>
{{if .F.FixedHeaders}}<dt>Fixed headers</dt><dd class="mono">{{range $k, $v := .F.FixedHeaders}}{{$k}}: {{$v}}<br>{{end}}</dd>{{end}}
{{with .OAuth2}}<dt>OAuth client ID</dt><dd class="mono">{{.ClientID}}</dd><dt>Token URL</dt><dd class="mono">{{.TokenURL}}</dd>{{if .ClientSecretKey}}<dt>Client secret</dt><dd class="mono">{{.ClientSecretKey}}{{if not $.SecretStored}} <span class="mute">(no value stored)</span>{{end}}</dd>{{end}}{{with .Scopes}}<dt>Scopes</dt><dd class="mono">{{range .}}{{.}}<br>{{end}}</dd>{{end}}{{end}}
{{if .F.ForwardRole}}<dt>Agent name</dt><dd>sent as <span class="mono">X-Keyring-Role</span></dd>{{end}}
{{if .F.ExtraHeaders}}<dt>Extra secret headers</dt><dd class="mono">{{range .F.ExtraHeaders}}{{.}}<br>{{end}}</dd>{{end}}
</dl></div>
{{if .Editable}}
Expand Down
11 changes: 7 additions & 4 deletions internal/dashboard/services.go
Original file line number Diff line number Diff line change
Expand Up @@ -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
}
Expand Down Expand Up @@ -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 {
Expand All @@ -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()
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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)},
} {
Expand Down
21 changes: 21 additions & 0 deletions internal/dashboard/services_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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)
}
}
13 changes: 13 additions & 0 deletions internal/policy/policy.go
Original file line number Diff line number Diff line change
Expand Up @@ -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"`
Expand Down Expand Up @@ -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")
}
Expand Down
4 changes: 4 additions & 0 deletions internal/server/server.go
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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")
Expand Down
35 changes: 35 additions & 0 deletions internal/server/server_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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)
}
}
}
Loading