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
10 changes: 8 additions & 2 deletions docs/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -193,8 +193,14 @@ Instructions, prompts, resources and tool descriptions are authored as markdown

**Needs approval** uses the MCP elicitation flow, shaped by the negotiated protocol revision (see [Protocol revision support](#protocol-revision-support)):

- If the client advertised elicitation (at initialise, or in the per-request `_meta` client capabilities on 2026-07-28), the server asks the user to approve the action (tool name, query class, SQL). On 2026-07-28 the prompt is returned as an `input_required` result carrying an `elicitation/create` input request under the id `stackql_approval`, and the client retries the call with the answer in `inputResponses`; on earlier revisions the server sends the `elicitation/create` request itself mid-call. Branch on the user response: `accept` -> proceed; `decline` or `cancel` -> return an error.
- If the client did **not** advertise elicitation, the tool is refused with a message that points the operator at `full_access` mode.
- If the client advertised elicitation (at initialise, or in the per-request `_meta` client capabilities on 2026-07-28), the server asks the user to approve the action (tool name, query class, SQL). On 2026-07-28 the prompt is returned as an `input_required` result carrying an `elicitation/create` input request under the id `stackql_approval`, and the client retries the call with the answer in `inputResponses` and the echoed `requestState`; on earlier revisions the server sends the `elicitation/create` request itself mid-call. Branch on the user response: `accept` -> proceed; `decline` or `cancel` -> return an error.
- If the client did **not** advertise elicitation, the tool is refused with a message that points the operator at `full_access` mode. This check runs before any answer is read, on the first call and on the retry.

**Approval binding.** The approval prompt carries an opaque `requestState` that the client echoes on the retry. It binds the answer to the prompt: it holds the tool name, a SHA-256 digest of the canonical arguments and SQL, the session id where the transport has one, a nonce and an expiry (10 minutes), and is authenticated with HMAC-SHA256 under a server key. An answer with missing, altered or expired state, or with state that no longer matches the tool, arguments or SQL of the call, is refused before the answer is read, and the backend is not called. On earlier revisions the SDK performs the round trip on the server side and echoes the state itself, so both lifecycles take the same check. Each process keeps a set of used nonces, so a state is accepted once.

The key is random per process by default, which suits `stdio` (one process per client, no session id) and a single HTTP instance. A sessionless Streamable HTTP deployment (`"stateless": true` or `protocol_version: 2026-07-28`) behind several instances needs one key on every instance: set `server.approval_key_env_var` to the name of an environment variable holding at least 32 bytes, read at startup in the same way as `auth_token_env_var`. The key never appears in logs or the audit sink. The used-nonce set is not shared across instances, so on such a deployment a replayed answer is bounded only by the expiry.

**Client trust.** `safe` and `delete_safe` trust the MCP client to show the prompt to a person and report the answer faithfully. The binding above rejects unsolicited, stale, altered and replayed answers from a cooperating client, but a malicious client can still accept its own prompt, so it is workflow integrity, not proof of human consent. Against untrusted clients use server-side restrictions: `read_only` mode, or a narrowed set of enabled tools.

The bundled `stackql_mcp_client` does NOT advertise elicitation, so against a `safe` or `delete_safe` server every mutation/lifecycle call is refused with the no-elicitation message. This is by design - the bundled client exists for scripting and regression tests, not interactive use. Elicitation-capable MCP clients (eg Claude Desktop, Cursor) prompt the user normally.

Expand Down
2 changes: 2 additions & 0 deletions pkg/mcp_server/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -335,6 +335,8 @@ A payload holding several statements is gated by its most privileged statement,

Approval is answered by the client, so it guards against an agent acting without its user, not against an untrusted caller; pair the HTTP transport with [client authentication](#http-client-authentication) where callers are not trusted.

The approval prompt carries a signed `requestState` that the client echoes with its answer, and an answer whose state is missing or does not match the call is refused before the backend runs. See [docs/mcp.md](/docs/mcp.md#server-modes) for the binding details and `server.approval_key_env_var` for sharing the signing key across instances.

The mode is global per server. There is no per-tool override in this release.

### Default-mode change (breaking)
Expand Down
200 changes: 200 additions & 0 deletions pkg/mcp_server/approval_state.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,200 @@
package mcp_server //nolint:revive // fine for now

import (
"crypto/hmac"
"crypto/rand"
"crypto/sha256"
"crypto/subtle"
"encoding/base64"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"os"
"strings"
"sync"
"time"
)

// approvalStateTTL bounds how long an approval prompt stays answerable. It
// also bounds replay across instances that share a key but not nonce state.
const approvalStateTTL = 10 * time.Minute

// minApprovalKeyBytes is the shortest key accepted from approval_key_env_var.
const minApprovalKeyBytes = 32

// approvalStateVersion tags the RequestState payload layout.
const approvalStateVersion = 1

// approvalBinding is what an approval answer must match on the retry: the
// tool, a digest over its canonical arguments and SQL, and the session the
// prompt was issued on (empty on stdio and on sessionless HTTP, where the
// per-process or shared key carries the binding instead).
type approvalBinding struct {
tool string
digest string
session string
}

// approvalClaims is the signed RequestState payload.
type approvalClaims struct {
V int `json:"v"`
Tool string `json:"tool"`
Digest string `json:"digest"`
Session string `json:"sid"`
Nonce string `json:"nonce"`
Exp int64 `json:"exp"` // unix milliseconds
}

// approvalBinder issues and verifies the RequestState that ties an approval
// answer to the prompt that asked for it (issue #827). The state is
// authenticated with HMAC-SHA256 under a server key, so sessionless
// transports need no server-side pending table. A consumed-nonce set blocks
// replay inside one process; across instances that share the key, replay is
// bounded only by approvalStateTTL.
//
// This is workflow integrity against stale, altered or unsolicited answers.
// It cannot prove a human saw the prompt: a client that lies about consent
// can still accept its own prompt.
type approvalBinder struct {
key []byte
ttl time.Duration
now func() time.Time

mu sync.Mutex
consumed map[string]time.Time // nonce -> expiry
}

// newApprovalBinder returns a binder keyed from server.approval_key_env_var
// when set, otherwise from a random per-process key. The key value is never
// included in errors or logs.
func newApprovalBinder(cfg *Config) (*approvalBinder, error) {
var key []byte
envVar := ""
if cfg != nil {
envVar = cfg.Server.ApprovalKeyEnvVar
}
if envVar != "" {
v := os.Getenv(envVar)
if v == "" {
return nil, fmt.Errorf("server.approval_key_env_var names an unset or empty env var %q", envVar)
}
if len(v) < minApprovalKeyBytes {
return nil, fmt.Errorf("server.approval_key_env_var %q must hold at least %d bytes", envVar, minApprovalKeyBytes)
}
key = []byte(v)
} else {
key = make([]byte, sha256.Size)
if _, err := rand.Read(key); err != nil {
return nil, fmt.Errorf("approval key: %w", err)
}
}
return &approvalBinder{
key: key,
ttl: approvalStateTTL,
now: time.Now,
consumed: map[string]time.Time{},
}, nil
}

// approvalDigest is the SHA-256 over the tool name, the canonical JSON of
// the typed arguments the handler will run with, and the SQL. Typed
// arguments marshal in struct field order, so the encoding is stable.
func approvalDigest(tool string, args any, sql string) (string, error) {
argsJSON, err := json.Marshal(args)
if err != nil {
return "", fmt.Errorf("canonical arguments: %w", err)
}
canonical, err := json.Marshal(struct {
Tool string `json:"tool"`
Args json.RawMessage `json:"args"`
SQL string `json:"sql"`
}{Tool: tool, Args: argsJSON, SQL: sql})
if err != nil {
return "", fmt.Errorf("canonical arguments: %w", err)
}
sum := sha256.Sum256(canonical)
return hex.EncodeToString(sum[:]), nil
}

// issue returns a fresh RequestState for the prompt bound to b.
func (a *approvalBinder) issue(b approvalBinding) (string, error) {
nonce := make([]byte, 16) //nolint:mnd // 128-bit nonce
if _, err := rand.Read(nonce); err != nil {
return "", fmt.Errorf("approval nonce: %w", err)
}
payload, err := json.Marshal(approvalClaims{
V: approvalStateVersion,
Tool: b.tool,
Digest: b.digest,
Session: b.session,
Nonce: hex.EncodeToString(nonce),
Exp: a.now().Add(a.ttl).UnixMilli(),
})
if err != nil {
return "", fmt.Errorf("approval state: %w", err)
}
enc := base64.RawURLEncoding
return enc.EncodeToString(payload) + "." + enc.EncodeToString(a.mac(payload)), nil
}

func (a *approvalBinder) mac(payload []byte) []byte {
h := hmac.New(sha256.New, a.key)
h.Write(payload)
return h.Sum(nil)
}

var (
errApprovalStateMissing = errors.New("no approval state was echoed with the answer")
errApprovalStateInvalid = errors.New("approval state is malformed or was not issued by this server")
errApprovalStateMismatch = errors.New("approval state does not match this call")
errApprovalStateExpired = errors.New("approval state has expired")
errApprovalStateReplayed = errors.New("approval state was already used")
)

// verify checks state against the current call and consumes its nonce. It
// runs before the answer is read, so a failed check never executes the tool.
// A failed check consumes nothing, so the legitimate retry still succeeds.
func (a *approvalBinder) verify(state string, b approvalBinding) error {
if state == "" {
return errApprovalStateMissing
}
payloadPart, sigPart, found := strings.Cut(state, ".")
if !found {
return errApprovalStateInvalid
}
enc := base64.RawURLEncoding
payload, err := enc.DecodeString(payloadPart)
if err != nil {
return errApprovalStateInvalid
}
sig, err := enc.DecodeString(sigPart)
if err != nil || !hmac.Equal(sig, a.mac(payload)) {
return errApprovalStateInvalid
}
var c approvalClaims
if uerr := json.Unmarshal(payload, &c); uerr != nil || c.V != approvalStateVersion || c.Nonce == "" {
return errApprovalStateInvalid
}
if c.Tool != b.tool || c.Session != b.session ||
subtle.ConstantTimeCompare([]byte(c.Digest), []byte(b.digest)) != 1 {
return errApprovalStateMismatch
}
now := a.now()
exp := time.UnixMilli(c.Exp)
if !now.Before(exp) {
return errApprovalStateExpired
}
a.mu.Lock()
defer a.mu.Unlock()
for n, e := range a.consumed {
if !now.Before(e) {
delete(a.consumed, n)
}
}
if _, used := a.consumed[c.Nonce]; used {
return errApprovalStateReplayed
}
a.consumed[c.Nonce] = exp
return nil
}
Loading