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
176 changes: 175 additions & 1 deletion docs/development/server-edition-multiuser-auth.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,180 @@ Server edition supports OAuth-based multi-user authentication with Google, GitHu
- **Admin**: Identified by `admin_emails` config. Sees all activity, manages users.
- **Build tag**: All server code behind `//go:build server`. Personal edition unaffected.

### Role freshness (issue #1169)

`admin_emails` is the single source of truth for the admin role, and **both**
auth paths re-derive it from the config on every request — the session path
always did, and the bearer-JWT path now does too. The `role` claim inside a JWT
is informational only; it is minted at login, never revoked, and must not be
trusted for authorization.

**An `admin_emails` edit takes effect on the next request — no restart.** The
config file is hot-reloadable (`config.LoadFromFile` unmarshals `server_edition`
in full, and it is not one of the restart-pinned fields), and the middleware
reads the role through a `ServerEditionConfigProvider` over the runtime's
current snapshot rather than a pointer captured at wiring time. It is the same
provider (`Dependencies.ConfigProvider`) the admin-servers check uses; do not
add a second mechanism, and do not capture `deps.Config.ServerEdition` in a new
surface that makes a role decision.

On both auth paths, once the file watcher has reloaded the edit:

- Removing someone from `admin_emails` demotes them on their next request, even
while they hold an unexpired admin JWT, and they can no longer renew an admin
token via `POST /api/v1/auth/token`. No re-login, no waiting for the JWT to
expire, and no restart.
- Adding someone promotes them on their next request, without re-login.

Two limits worth stating exactly, because they are what the guarantee does
*not* cover:

- The edit is live from the moment the **reload lands**, not from the moment the
file is saved. A malformed file is rejected and the previous config stays in
force (`Config hot-reload failed; keeping previous configuration`), so confirm
the reload before treating anyone as demoted.
- If a reload produces a config with **no `server_edition` block at all**, the
provider falls back to the boot-time block rather than emptying the admin
list. That is the conservative direction — it can only preserve the list the
process started with, never widen it.

`AdminHandlers.adminEmails` is a separate, boot-time copy used **only** to
label rows in the dashboard response. It is not an access-control input (every
admin route gates on `requireAdmin` → `AuthContext.IsAdmin()`), so a stale label
there is cosmetic. Do not grow an authorization check on top of it.

### Agent tokens and tenant identity (issue #1168)

- Agent-token names are a **per-owner** namespace: two tenants can each hold a
token called `ci`. Storage resolves by `(owner, name)`; the legacy
`agent_token_names` index is kept only for ownerless (personal-edition)
tokens, and there is no migration.
- `/api/v1/user/tokens/{name}` revoke, delete and regenerate answer an
identical **404** for "does not exist" and "belongs to another tenant", and
create no longer reports a conflict on another tenant's name. Do not
reintroduce a "not yours" branch — it is a name-existence oracle.
- Those three do the lookup **inside the mutating transaction** and classify its
error (`storage.ErrAgentTokenNotFound` → 404). Do not put a `Get…` preflight
back in front: it opens a TOCTOU window on delete-then-recreate, and its
fall-through 500 used to interpolate the storage sentinel into the body.
- The token cap answers **409** on both editions' surfaces
(`ErrAgentTokenLimitReached`). One storage condition, one status. The **body
differs by edition on purpose**: `auth.MaxTokens` is counted across the whole
`agent_tokens` bucket, so in the server edition it is a *deployment-wide* cap
a tenant may be unable to clear, and the message says so and points at an
administrator. Do not copy the personal edition's "you have reached the
maximum" wording here. A per-owner quota is issue #1177.
- **A token is only as live as its owner.** `storage.Manager.SetAgentTokenOwnerGate`
is installed in `setup.go` over the user store, and `ValidateAgentToken`
consults it for every *owned* token (ownerless personal-edition tokens are
never gated). A disabled — or deleted — owner's tokens stop authenticating
immediately, and the gate **fails closed**: a user store that cannot answer
denies. `POST /api/v1/admin/users/{id}/disable` additionally **revokes** that
user's tokens, so re-enabling the account does not resurrect a credential that
may be why it was disabled; `enable` deliberately does not un-revoke, and
**neither does regenerate** — rotating a revoked token answers `409`
(`storage.ErrAgentTokenRevoked`) on both editions' surfaces, because rotation
refreshes a live secret and is not an un-revoke by another name. Delete frees
the name, so creating a fresh token is the supported path. An admin-facing
surface for revoking a *specific* tenant's token is issue #1179.
- **The owner gate is installed FIRST in `setup.go`, before any fallible step.**
`wireServerEditionOAuth` only *logs* `SetupAll`'s error — the process comes up
serving traffic either way — so a control installed after `cfg.Validate()`,
`EnsureBuckets()`, `GetOrCreateHMACKey()` or the credential store is simply
absent whenever one of those fails, and agent tokens would then be ungated.
Installed first it fails closed instead. Keep new fallible setup steps *below*
it.
- `RegenerateAgentTokenForOwner`'s `narrowScope` hook can only ever narrow, and
storage **enforces** that: the hook's return is intersected with the token's
stored `AllowedServers` before it is persisted (a stored `"*"` counts as
granting everything, so materialising it into a concrete list still works).
The contract is not a comment a future caller can violate.
- An agent token's `AuthContext` carries its owner's `UserID` (so its activity
is attributable) but stays at `AuthTypeAgent`. Per-user surfaces must gate on
`IsUser()`, never on a non-empty `UserID`.
- The personal-edition admin surface (`/api/v1/tokens/{name}`) operates in the
ownerless namespace and therefore no longer reaches server-edition users'
tokens by name. Cross-tenant token administration belongs in
`admin_handlers` as its own feature.

### Token server scope (`allowed_servers`)

`POST /api/v1/user/tokens` constrains the requested `allowed_servers` to what
the caller may actually reach. `AllowedServers` is the sole input to
`auth.AuthContext.CanAccessServer`, so persisting it verbatim let a tenant mint
themselves a token over the admin's whole inventory.

- **Entitlement is the per-user door's own predicate**: the caller's personal
servers plus the admin servers flagged `shared`. `NewUserHandlers` receives
the *whole* configuration, so the `Shared` filter is what keeps the admin's
private servers out. Reuse `entitledServerNames`; do not write a second
definition of entitlement.
- **Read the configuration LIVE, never a boot-time slice.** `NewUserHandlers`
takes an `AdminServersProvider` (a function), wired in `setup.go` to
`Dependencies.ConfigProvider` over the runtime's current config snapshot. The
config is hot-reloadable: a handler built on `deps.Config.Servers` as captured
at process start is blind to every server added afterwards, and a tenant could
pre-create a personal server named like an admin server that only appears
later and walk straight through the collision control below. Any new
server-edition surface that makes an authorisation decision from configuration
must read it through the provider.
- **An unentitled name is rejected (400), not silently dropped** — a token that
quietly sees less than asked is worse than a refusal. The message is
identical for "another tenant's server", "the admin's unshared server" and
"no such server anywhere": a distinguishing message would be a server-name
existence oracle, the same defect class as the token-name one above.
- **`"*"`** is the only wildcard the enforcement layer honours (`s == "*" ||
s == name`, in both `auth` and `jsruntime`), so there are no globs to expand.
For an admin it stays literal; for a tenant it is materialised into their
entitled set at mint time, and refused outright when that set is empty. The
expansion is a snapshot — a server added later needs a new token — and the
create response echoes the effective list back.
- **An omitted `allowed_servers` stays empty**, which denies every server at the
agent tier. Do not copy the personal edition's "empty means `["*"]`" default:
there the only caller is the operator.
- **A personal server may not take a name used anywhere in the admin
configuration**, shared or private. `AllowedServers` is compared by bare
string, so "I own a server called X" and "I may reach the admin's X" are
indistinguishable at enforcement time — a personal server named after an
admin-private upstream was a way to mint a token over it.
`entitledServerNames` also drops such a collision for a non-admin, so a row
that predates the refusal (or an admin who later adds a colliding name) cannot
resurrect the escalation. **`createServer` answers every unavailable name with
one body** — `Server name %q is not available` — whether the holder is a
shared admin server, a private admin server, or the caller's own existing
server. Two different wordings let a tenant read, from one request, that a
name they do not own is in the admin's configuration, and enumerate a private
inventory they cannot list. The residual bit (a tenant can subtract their own
inventory) closes only when enforcement resolves a server name against an
owner rather than as a bare string.

#### Scope is a snapshot, not a live check

`resolveTokenServerScope` runs at mint time and **nothing re-validates at use
time**. Un-sharing a server, or removing a personal one, does **not** revoke the
grants already written into live tokens — to actually withdraw access, revoke or
delete the tokens.

Rotation is the one re-check: `POST /api/v1/user/tokens/{name}/regenerate`
re-runs the entitlement predicate and persists the **narrowed** list
(`narrowScopeToEntitled`), echoing it back in the response. It only ever narrows,
and it never rejects — refusing to rotate would leave the over-broad grant in
place and working. A token that is never rotated is never re-checked.

**Tokens minted with a literal `"*"` before this constraint existed.** The
enforcement layer honours `"*"` unconditionally, so any such token is a standing
grant over the whole deployment. There is no migration and no admin-facing
report: `GET /api/v1/user/tokens` is per-caller, and the server edition has no
cross-tenant token listing (that belongs in `admin_handlers`, as its own
feature). Until one exists, an operator audits them straight from storage —
every record in the `agent_tokens` bucket whose `allowed_servers` contains `"*"`
and whose `user_id` is non-empty — and revokes them; a tenant's own rotation
also materialises the star into their entitled set. **This does not block the
release**: the escalation route is closed for every token minted from here on,
and a pre-existing `"*"` token could only have been minted by a tenant who was
already able to mint one, i.e. it is not a new exposure. It is a cleanup item to
carry into the cross-tenant token administration feature.

## Key Directories

| Directory | Purpose |
Expand All @@ -66,7 +240,7 @@ Server edition supports OAuth-based multi-user authentication with Google, GitHu
| `internal/serveredition/auth/` | OAuth, sessions, JWT tokens, middleware |
| `internal/serveredition/users/` | User/session models, BBolt store |
| `internal/serveredition/workspace/` | Per-user workspace for personal upstreams |
| `internal/serveredition/multiuser/` | Multi-user router, tool filtering, activity isolation |
| `internal/serveredition/multiuser/` | Multi-user router (**not yet wired** — `NewRouter` has no production caller), tool filtering, activity isolation |
| `internal/serveredition/api/` | Server REST API endpoints (user, admin, auth) |

## Server Testing
Expand Down
7 changes: 7 additions & 0 deletions internal/auth/agent_token.go
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,13 @@ func (t *AgentToken) AuthContext() *AuthContext {
AllowedServers: t.AllowedServers,
Permissions: t.Permissions,
ProfilePin: t.ProfilePin,
// UserID carries the owning tenant (server edition). Without it an
// agent-token request had no tenant identity at all, so its activity
// could not be attributed or scoped. It does NOT confer the user tier:
// Type stays AuthTypeAgent, so IsUser()/IsAdmin() remain false, and
// every per-user surface must gate on IsUser() rather than on a
// non-empty UserID.
UserID: t.UserID,
}
}

Expand Down
108 changes: 108 additions & 0 deletions internal/auth/agent_token_identity_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,108 @@
package auth

import (
"reflect"
"testing"
)

// TestAgentTokenAuthContext_CarriesUserID: an agent-token request must carry
// the owning tenant's identity, or its activity cannot be attributed or scoped
// at all (issue #1168 gap b).
//
// BITES: without the fix ac.UserID is "" while the token names an owner.
func TestAgentTokenAuthContext_CarriesUserID(t *testing.T) {
const owner = "01HTEST000000000000000USER"

tok := &AgentToken{
Name: "ci",
TokenPrefix: "mcp_agt_abcd",
Permissions: []string{PermRead},
UserID: owner,
}

ac := tok.AuthContext()
if ac == nil {
t.Fatal("AuthContext() returned nil for a valid token")
}
if ac.UserID != owner {
t.Errorf("UserID = %q, want %q — the agent tier carries no tenant identity", ac.UserID, owner)
}
if ac.GetUserID() != owner {
t.Errorf("GetUserID() = %q, want %q", ac.GetUserID(), owner)
}

// Carrying the owner must NOT promote the tier: everything gated on the
// user tier stays closed, and admin stays closed.
if ac.Type != AuthTypeAgent {
t.Errorf("Type = %q, want %q", ac.Type, AuthTypeAgent)
}
if ac.IsUser() {
t.Error("an agent token must not satisfy IsUser(); per-user surfaces gate on it")
}
if ac.IsAdmin() {
t.Error("an agent token must never be admin")
}
if ac.CanRevealSecrets() {
t.Error("an agent token must never be allowed to reveal secrets")
}
}

// TestAgentTokenAuthContext_FieldParity_Reflective makes the constructor's own
// doc-comment promise ("so no auth path can silently drop a field") into a
// mechanical check: every AgentToken field with a same-named counterpart on
// AuthContext must be carried through. The next field added to AgentToken
// fails here instead of being dropped in silence — which is exactly how UserID
// went missing.
//
// Fields with no AuthContext counterpart (TokenHash, ExpiresAt, CreatedAt,
// LastUsedAt, Revoked) are storage bookkeeping and are skipped. Name maps to
// AgentName and is checked explicitly.
func TestAgentTokenAuthContext_FieldParity_Reflective(t *testing.T) {
tok := &AgentToken{
Name: "ci",
TokenPrefix: "mcp_agt_abcd",
AllowedServers: []string{"github"},
Permissions: []string{PermRead},
UserID: "01HTEST000000000000000USER",
ProfilePin: "work",
}

ac := tok.AuthContext()
if ac == nil {
t.Fatal("AuthContext() returned nil for a valid token")
}

if ac.AgentName != tok.Name {
t.Errorf("AgentName = %q, want the token's Name %q", ac.AgentName, tok.Name)
}

tokVal := reflect.ValueOf(*tok)
tokType := tokVal.Type()
acVal := reflect.ValueOf(*ac)
acType := acVal.Type()

checked := 0
for i := 0; i < tokType.NumField(); i++ {
f := tokType.Field(i)
acField, ok := acType.FieldByName(f.Name)
if !ok || acField.Type != f.Type {
continue // no same-named, same-typed counterpart
}
src := tokVal.Field(i)
if src.IsZero() {
continue // the fixture does not exercise this field
}
checked++
if !reflect.DeepEqual(src.Interface(), acVal.FieldByName(f.Name).Interface()) {
t.Errorf("AuthContext() dropped %s: token has %v, context has %v",
f.Name, src.Interface(), acVal.FieldByName(f.Name).Interface())
}
}

// Guard against the check silently covering nothing (a renamed field, a
// changed type). TokenPrefix, AllowedServers, Permissions, UserID and
// ProfilePin all have counterparts today.
if checked < 5 {
t.Fatalf("the reflective parity check only covered %d fields; it is no longer proving anything", checked)
}
}
2 changes: 1 addition & 1 deletion internal/httpapi/auth_middleware_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ func (s *testTokenStore) DeleteAgentToken(_ string) error
func (s *testTokenStore) RegenerateAgentToken(_ string, _ string, _ []byte) (*auth.AgentToken, error) {
return nil, nil
}
func (s *testTokenStore) UpdateAgentTokenLastUsed(_ string) error { return nil }
func (s *testTokenStore) UpdateAgentTokenLastUsedByHash(_ string) error { return nil }

func (s *testTokenStore) ValidateAgentToken(rawToken string, hmacKey []byte) (*auth.AgentToken, error) {
if s.validateFunc != nil {
Expand Down
2 changes: 1 addition & 1 deletion internal/httpapi/server.go
Original file line number Diff line number Diff line change
Expand Up @@ -552,7 +552,7 @@ func (s *Server) handleAgentTokenAuth(w http.ResponseWriter, r *http.Request, ne

// Update last-used timestamp in background
go func() {
if updateErr := s.tokenStore.UpdateAgentTokenLastUsed(agentToken.Name); updateErr != nil {
if updateErr := s.tokenStore.UpdateAgentTokenLastUsedByHash(agentToken.TokenHash); updateErr != nil {
s.logger.Warnw("Failed to update agent token last-used timestamp",
zap.String("name", agentToken.Name),
zap.Error(updateErr))
Expand Down
27 changes: 23 additions & 4 deletions internal/httpapi/tokens.go
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ package httpapi

import (
"encoding/json"
"errors"
"fmt"
"net/http"
"regexp"
Expand All @@ -13,6 +14,7 @@ import (

"github.com/smart-mcp-proxy/mcpproxy-go/internal/auth"
"github.com/smart-mcp-proxy/mcpproxy-go/internal/contracts"
"github.com/smart-mcp-proxy/mcpproxy-go/internal/storage"
)

// TokenStore defines the storage interface for agent token CRUD operations.
Expand All @@ -25,7 +27,10 @@ type TokenStore interface {
DeleteAgentToken(name string) error
RegenerateAgentToken(name string, newRawToken string, hmacKey []byte) (*auth.AgentToken, error)
ValidateAgentToken(rawToken string, hmacKey []byte) (*auth.AgentToken, error)
UpdateAgentTokenLastUsed(name string) error
// UpdateAgentTokenLastUsedByHash is keyed by the token's HMAC hash, not by
// its name: names are unique only within an owner in the server edition,
// so a by-name stamp could land on another tenant's token.
UpdateAgentTokenLastUsedByHash(hash string) error
}

// ServerNameLister provides the list of known server names for allowed_servers validation.
Expand Down Expand Up @@ -189,9 +194,15 @@ func (s *Server) handleCreateToken(w http.ResponseWriter, r *http.Request) {
}

if err := s.tokenStore.CreateAgentToken(agentToken, rawToken, hmacKey); err != nil {
// Check for duplicate name
if strings.Contains(err.Error(), "already exists") {
s.writeError(w, r, http.StatusConflict, err.Error())
// Check for duplicate name. Classified on a typed sentinel rather than
// a substring of the storage message, so the response never echoes
// storage internals.
if errors.Is(err, storage.ErrAgentTokenNameExists) || strings.Contains(err.Error(), "already exists") {
s.writeError(w, r, http.StatusConflict, fmt.Sprintf("A token named %q already exists", req.Name))
return
}
if errors.Is(err, storage.ErrAgentTokenLimitReached) {
s.writeError(w, r, http.StatusConflict, fmt.Sprintf("Maximum number of agent tokens (%d) reached", auth.MaxTokens))
return
}
s.logger.Errorf("Failed to create agent token: %v", err)
Expand Down Expand Up @@ -360,6 +371,14 @@ func (s *Server) handleRegenerateToken(w http.ResponseWriter, r *http.Request) {
s.writeError(w, r, http.StatusNotFound, fmt.Sprintf("Token %q not found", name))
return
}
// Rotation refreshes a live secret; it is not an un-revoke. Classified
// here so the refusal is a 409 with an actionable body rather than the
// generic 500 the fall-through would produce.
if errors.Is(err, storage.ErrAgentTokenRevoked) {
s.writeError(w, r, http.StatusConflict,
fmt.Sprintf("Token %q is revoked and cannot be regenerated. Delete it and create a new token.", name))
return
}
s.logger.Errorf("Failed to regenerate agent token: %v", err)
s.writeError(w, r, http.StatusInternalServerError, "Failed to regenerate token")
return
Expand Down
Loading
Loading