fix(webhook): keep a route path out of the sender identity

A webhook set SenderID to its configured route path. The turn path reads that
field through a per-channel resolver which refuses webhook, but the session
curator derives its participant from the raw field with no channel filter, so a
webhook session with exactly one distinct sender and one extracted fact wrote
agent-user memory addressed to User: "/hooks/...". Nothing reads it, and every
pass added more, because the facts are identical strings with no dedup.
docs/prds/memory-engine-unification.md criterion 7 requires that a route path
never become a user identity.

Clear it at the producer rather than teaching every consumer which channels are
lying: a route path is a source, not a person, so it no longer enters SenderID.
It still keys the inbound rate limit, where it is the documented per-source
budget for webhooks (config.RateLimitConfig), so it travels in the new
transport-only Inbound.BudgetKey -- carried on the wire beside Page, never
persisted, and never read as an identity.

pb.Message gains budget_key (field 9) for the same reason page (field 7) exists:
transport context that rides with an inbound message and is deliberately absent
from storedProto's rendering of a canonical record.

The curator needs no change. An empty SenderID already fails closed as an
unidentified user message, which is the path a dashboard session takes, and
sessionParticipant's existing skip covers it; the test name now says so.
This commit is contained in:
sam committed 2026-09-22 03:18:59 +10:00
1 parent a0170df7cb
commit 1fe4691bd6
16 files changed
+220 -74

No files matched your search

+3 -2
View File
@@ -186,8 +186,9 @@ class = "ollama"
# Per-(channel, sender) inbound rate limiting, shared by every chat channel:
# Telegram keys by numeric user ID, email by SMTP from address, webhook by
# its configured route path. Off by default -- both fields must be set to a
# positive value.
# its configured route path -- a source, not a person, so it reaches the
# limiter as a transport-only budget key rather than as an identity. Off by
# default -- both fields must be set to a positive value.
# [chat.rate_limit]
# window = "1m"
# max_requests = 20
+12 -9
View File
@@ -36,11 +36,13 @@ Three further defects fall out of the same split:
string`, and the curator fills it with a **session id** (`sessioncurator.go`)
— which is none of the four scopes `docs/architecture/agent-system.md`
requires, and stops meaning anything when the session ends.
3. **The chat turn has no user identity on half the channels.** `SenderID` is
populated by Telegram and email (a person) and by webhook (a **route path**,
`webhook.go`), and not at all by the dashboard, whose gateway wire message
carries no sender field. It is also never persisted: `sender_id` appears
nowhere in `session_store_sqlite.go`.
3. **The chat turn has no user identity on half the channels.** Telegram and
email populate `SenderID` with a person; the dashboard populates it with
nothing, and a webhook populates it with nothing either — a route path names
a source, not a person, so `webhook.go` leaves `SenderID` empty and carries
the route in `Inbound.BudgetKey` for rate limiting. `sender_id` is persisted
(`session_store_sqlite.go`), so whatever a channel puts there reaches the
consumers that read it.
`agent-system.md` says the write-scope selection and cross-scope sharing
rules "require a focused memory design decision". This is that decision.
@@ -149,10 +151,11 @@ UserIdentity func(msg messaging.Message) (IdentityID, bool)
```
This must be injectable rather than a blanket `channel + ":" + SenderID`
concatenation, because a **webhook's `SenderID` is a route path**
(`webhook.go`), not a person; treating it as one would give a URL an
identity. Telegram and email supply their sender id; the dashboard and webhook
resolve nothing.
concatenation, because a channel's sender id is not necessarily a person: a
webhook's route path names a source, and treating it as an identity would give
a URL one -- which is why `webhook.go` leaves `SenderID` empty and carries the
route in `Inbound.BudgetKey` instead. Telegram and email supply their sender
id; the dashboard and webhook resolve nothing.
**Fail closed.** When `UserID` is empty the turn proceeds with global and agent
scopes only, and a write targeting `user` or `agent-user` fails with a clear
+8 -6
View File
@@ -13,12 +13,14 @@ import (
//
// Telegram and email carry a native per-person sender id (a Telegram numeric
// user id, an SMTP from address). The dashboard ("web") has one bearer
// token, not users, and a webhook's SenderID is the configured route path
// (internal/channels/webhook/webhook.go), not a person -- treating either as
// an identity would give a URL or a shared token the same standing as a
// real user, which the read path's isolation guarantee depends on never
// happening. Both resolve nothing, so a turn on either channel gets global
// and agent scopes only (Subject.WritableScopes' fail-closed behaviour).
// token, not users, and a webhook carries no per-caller identity at all: its
// route path is a source, not a person, and never enters SenderID
// (internal/channels/webhook/webhook.go -- it travels in the transport-only
// Inbound.BudgetKey instead). Treating a URL or a shared token as an
// identity would give it the same standing as a real user, which the read
// path's isolation guarantee depends on never happening. Both resolve
// nothing, so a turn on either channel gets global and agent scopes only
// (Subject.WritableScopes' fail-closed behaviour).
func userIdentityResolver(channel string) func(messaging.Message) (memory.IdentityID, bool) {
switch channel {
case "telegram", "email":
+17 -10
View File
@@ -170,16 +170,23 @@ func (g *Gateway) handleWebhook(route *RouteConfig) http.HandlerFunc {
return
}
msg := messaging.Inbound{Message: messaging.Message{
ConversationID: messaging.ConversationID{ChannelID: route.Path},
Sender: "webhook",
// Webhooks have no per-caller identity; the configured route
// is the closest thing to one, since it corresponds to a
// single external source.
SenderID: route.Path,
Role: messaging.RoleUser,
Text: text,
}}
msg := messaging.Inbound{
Message: messaging.Message{
ConversationID: messaging.ConversationID{ChannelID: route.Path},
Sender: "webhook",
// A webhook has no per-caller identity, so SenderID stays
// empty: consumers read it as a person
// (internal/app/archied/chat_identity.go, sessioncurator),
// and a route path must never become a user identity
// (docs/prds/memory-engine-unification.md criterion 7).
Role: messaging.RoleUser,
Text: text,
},
// The route is still this message's source for inbound rate
// limiting, so it travels in the transport-only BudgetKey
// rather than borrowing the identity field.
BudgetKey: route.Path,
}
reply, err := client.Route(r.Context(), msg)
if err != nil {
g.log.Error("webhook route", "err", err, "path", route.Path)
+18 -7
View File
@@ -87,10 +87,10 @@ func TestWebhookHandlerNotStarted(t *testing.T) {
func TestWebhookHandlerRoute(t *testing.T) {
log := slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: slog.LevelWarn}))
g := New("", 0, []RouteConfig{{Path: "/hook"}}, log)
var gotSenderID string
var got messaging.Inbound
g.client = &fakeChatContract{
routeFunc: func(ctx context.Context, in messaging.Inbound) (messaging.ChatReply, error) {
gotSenderID = in.Message.SenderID
routeFunc: func(_ context.Context, in messaging.Inbound) (messaging.ChatReply, error) {
got = in
return messaging.ChatReply{Text: "ok"}, nil
},
}
@@ -102,10 +102,21 @@ func TestWebhookHandlerRoute(t *testing.T) {
if rec.Code != http.StatusAccepted {
t.Errorf("status = %d, want 202", rec.Code)
}
// Webhook has no native per-caller identity, so the configured route
// path is used to key rate limiting instead (see internal/ratelimit).
if gotSenderID != "/hook" {
t.Errorf("SenderID = %q, want the route path", gotSenderID)
// A webhook has no per-caller identity, and the route path is not one:
// several consumers read SenderID as a person
// (internal/app/archied/chat_identity.go, sessioncurator), and criterion
// 7 of docs/prds/memory-engine-unification.md says a route path must
// never become one. It still keys this message's inbound rate limit, so
// it travels in the transport-only BudgetKey instead -- see
// internal/ratelimit and config.RateLimitConfig.
if got.Message.SenderID != "" {
t.Errorf("SenderID = %q, want empty: a route path is not a person", got.Message.SenderID)
}
if got.BudgetKey != "/hook" {
t.Errorf("BudgetKey = %q, want the route path", got.BudgetKey)
}
if got.Message.ConversationID.ChannelID != "/hook" {
t.Errorf("ConversationID.ChannelID = %q, want the route path", got.Message.ConversationID.ChannelID)
}
}
+5 -2
View File
@@ -975,8 +975,11 @@ type ChatConfig struct {
// RateLimitConfig configures the sliding-window inbound rate limiter
// (internal/ratelimit) shared by every chat channel. A sender is
// identified per channel: Telegram by numeric user ID, email by the SMTP
// from address, webhook by the configured route path. Disabled unless
// both fields are set to a positive value.
// from address, webhook by the configured route path -- which is a source,
// not a person, so it reaches the limiter through the transport-only
// Inbound.BudgetKey rather than through SenderID (see
// docs/prds/memory-engine-unification.md §3). Disabled unless both fields
// are set to a positive value.
type RateLimitConfig struct {
// Window is the rolling interval MaxRequests is budgeted over.
Window time.Duration `toml:"window" yaml:"window"`
+27 -11
View File
@@ -139,15 +139,22 @@ func (x *Session) GetLastActiveAt() *timestamppb.Timestamp {
}
type Message struct {
state protoimpl.MessageState `protogen:"open.v1"`
MessageId string `protobuf:"bytes,1,opt,name=message_id,json=messageId,proto3" json:"message_id,omitempty"`
SourceId string `protobuf:"bytes,2,opt,name=source_id,json=sourceId,proto3" json:"source_id,omitempty"`
ChannelId string `protobuf:"bytes,3,opt,name=channel_id,json=channelId,proto3" json:"channel_id,omitempty"`
ThreadId string `protobuf:"bytes,4,opt,name=thread_id,json=threadId,proto3" json:"thread_id,omitempty"`
From string `protobuf:"bytes,5,opt,name=from,proto3" json:"from,omitempty"`
Text string `protobuf:"bytes,6,opt,name=text,proto3" json:"text,omitempty"`
Page string `protobuf:"bytes,7,opt,name=page,proto3" json:"page,omitempty"`
At *timestamppb.Timestamp `protobuf:"bytes,8,opt,name=at,proto3" json:"at,omitempty"`
state protoimpl.MessageState `protogen:"open.v1"`
MessageId string `protobuf:"bytes,1,opt,name=message_id,json=messageId,proto3" json:"message_id,omitempty"`
SourceId string `protobuf:"bytes,2,opt,name=source_id,json=sourceId,proto3" json:"source_id,omitempty"`
ChannelId string `protobuf:"bytes,3,opt,name=channel_id,json=channelId,proto3" json:"channel_id,omitempty"`
ThreadId string `protobuf:"bytes,4,opt,name=thread_id,json=threadId,proto3" json:"thread_id,omitempty"`
From string `protobuf:"bytes,5,opt,name=from,proto3" json:"from,omitempty"`
Text string `protobuf:"bytes,6,opt,name=text,proto3" json:"text,omitempty"`
Page string `protobuf:"bytes,7,opt,name=page,proto3" json:"page,omitempty"`
At *timestamppb.Timestamp `protobuf:"bytes,8,opt,name=at,proto3" json:"at,omitempty"`
// budget_key is the source an inbound message is charged against by the
// Gateway's inbound rate limiter, for a channel that has no per-person
// sender id but does have a stable, operator-controlled source of its own
// -- a webhook's configured route path. Transport-only: a channel frontend
// sets it on inbound and it is never persisted, exactly like page. Empty
// means the message is not rate limited.
BudgetKey string `protobuf:"bytes,9,opt,name=budget_key,json=budgetKey,proto3" json:"budget_key,omitempty"`
unknownFields protoimpl.UnknownFields
sizeCache protoimpl.SizeCache
}
@@ -238,6 +245,13 @@ func (x *Message) GetAt() *timestamppb.Timestamp {
return nil
}
func (x *Message) GetBudgetKey() string {
if x != nil {
return x.BudgetKey
}
return ""
}
type ToolCall struct {
state protoimpl.MessageState `protogen:"open.v1"`
Id string `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"`
@@ -2758,7 +2772,7 @@ const file_gateway_v1_chat_proto_rawDesc = "" +
"\n" +
"created_at\x18\t \x01(\v2\x1a.google.protobuf.TimestampR\tcreatedAt\x12@\n" +
"\x0elast_active_at\x18\n" +
" \x01(\v2\x1a.google.protobuf.TimestampR\flastActiveAt\"\xe9\x01\n" +
" \x01(\v2\x1a.google.protobuf.TimestampR\flastActiveAt\"\x88\x02\n" +
"\aMessage\x12\x1d\n" +
"\n" +
"message_id\x18\x01 \x01(\tR\tmessageId\x12\x1b\n" +
@@ -2769,7 +2783,9 @@ const file_gateway_v1_chat_proto_rawDesc = "" +
"\x04from\x18\x05 \x01(\tR\x04from\x12\x12\n" +
"\x04text\x18\x06 \x01(\tR\x04text\x12\x12\n" +
"\x04page\x18\a \x01(\tR\x04page\x12*\n" +
"\x02at\x18\b \x01(\v2\x1a.google.protobuf.TimestampR\x02at\"|\n" +
"\x02at\x18\b \x01(\v2\x1a.google.protobuf.TimestampR\x02at\x12\x1d\n" +
"\n" +
"budget_key\x18\t \x01(\tR\tbudgetKey\"|\n" +
"\bToolCall\x12\x0e\n" +
"\x02id\x18\x01 \x01(\tR\x02id\x12\x12\n" +
"\x04name\x18\x02 \x01(\tR\x04name\x12\x1e\n" +
+2 -2
View File
@@ -90,8 +90,8 @@ const (
// AgentID and IdentityID are opaque. This package never resolves them,
// canonicalises them, or invents one from a channel: resolution happens
// where the channel's native identity is in hand (the gateway turn path),
// because a webhook's sender id is a route path and treating it as a person
// would give a URL an identity.
// because a channel's sender id is not necessarily a person -- treating one
// as a person would give a URL an identity.
type (
AgentID string
IdentityID string
+13
View File
@@ -22,6 +22,19 @@ type Inbound struct {
// this message. Transport-only: it reaches the system prompt and
// is never persisted. Empty for non-web channels.
Page string
// BudgetKey is what the Gateway charges this message against in its
// inbound rate limiter (internal/ratelimit), for a channel whose
// Message.SenderID is empty because it carries no per-person
// identity but still has a stable, operator-controlled source to
// budget -- a webhook's configured route path, today. It is
// deliberately not SenderID: SenderID means "this is who sent it",
// and several consumers (internal/app/archied/chat_identity.go,
// sessioncurator) read it as a person, so a route path in that field
// becomes a user identity. BudgetKey is transport-only and never
// persisted, exactly like Page. Empty means the message is not
// rate limited, which is correct for a source with no stable key of
// its own (the dashboard).
BudgetKey string
}
// SpawnRequest is a chat-originated task creation request. Repo and
+9 -5
View File
@@ -91,11 +91,15 @@ type Message struct {
Sender string
// SenderID is the channel-native stable identifier for the party that
// sent this message (e.g. a Telegram numeric user ID, an SMTP from
// address, or a webhook route path), distinct from Sender's
// human-readable display form. Empty when the channel has no stable
// per-sender identity to offer. Used to key per-identity inbound
// controls such as rate limiting.
// sent this message (e.g. a Telegram numeric user ID or an SMTP from
// address), distinct from Sender's human-readable display form. Empty
// when the channel has no stable per-person identity to offer -- which
// includes a webhook, whose configured route path is a source rather
// than a person and travels in the transport-only Inbound.BudgetKey
// instead (see docs/prds/memory-engine-unification.md §3). Used to key
// per-identity inbound controls and to derive a memory participant, so
// a non-person value here becomes a user identity to every consumer
// that reads it.
SenderID string
Role Role
+28 -13
View File
@@ -203,10 +203,12 @@ type Router struct {
// path. Nil drops those diagnostics silently; nothing on this path is
// important enough to fail the turn over.
Log *slog.Logger
// Limiter enforces a per-(gateway, sender) inbound budget when set.
// Nil disables rate limiting entirely. Messages with no SenderID
// (channels that cannot supply a stable per-sender identity) are
// never limited, since there is no key to charge them against.
// Limiter enforces a per-(gateway, source) inbound budget when set.
// Nil disables rate limiting entirely. A message is charged against
// Inbound.BudgetKey when the channel set one (a webhook route, which
// has a stable source but no person), else against Message.SenderID.
// A message with neither is never limited: there is no key to charge
// it against.
Limiter *ratelimit.Limiter
sessionTracker *sessionTracker
gatewayName string
@@ -240,21 +242,34 @@ func (r *Router) SessionTracker() *sessionTracker {
// budget, in place of normal dispatch.
const rateLimitReply = "You're sending messages too quickly. Please wait a moment and try again."
// checkRateLimit reports whether msg is over its sender's inbound budget.
// A nil Limiter (rate limiting not configured) or an empty SenderID
// (the channel has no stable per-sender identity to charge) always
// allows.
func (r *Router) checkRateLimit(msg messaging.Message) (blocked bool) {
if r.Limiter == nil || msg.SenderID == "" {
// checkRateLimit reports whether in is over its source's inbound budget.
// A nil Limiter (rate limiting not configured) or no key to charge the
// message against (see inboundBudgetKey) always allows.
func (r *Router) checkRateLimit(in Inbound) (blocked bool) {
key := inboundBudgetKey(in)
if r.Limiter == nil || key == "" {
return false
}
return !r.Limiter.Allow(r.gatewayName, msg.SenderID)
return !r.Limiter.Allow(r.gatewayName, key)
}
// inboundBudgetKey returns the key this message's inbound budget is charged
// against: the channel's own transport budget key when it set one, else the
// per-person SenderID. The two are deliberately distinct -- SenderID means
// "who sent this", and a channel whose SenderID is not a person (a webhook
// route path) must not put it there, because several consumers read that
// field as a user identity (docs/prds/memory-engine-unification.md §3).
func inboundBudgetKey(in Inbound) string {
if in.BudgetKey != "" {
return in.BudgetKey
}
return in.Message.SenderID
}
// Route dispatches msg and returns the reply. Gateway-local commands
// are handled directly; everything else goes to the LLM responder.
func (r *Router) Route(ctx context.Context, in Inbound) (string, error) {
if r.checkRateLimit(in.Message) {
if r.checkRateLimit(in) {
return rateLimitReply, nil
}
return r.route(ctx, in)
@@ -433,7 +448,7 @@ func (r *Router) RouteStream(ctx context.Context, in Inbound, stream TurnStream)
if r.LLMStream == nil || stream == nil {
return r.Route(ctx, in)
}
if r.checkRateLimit(in.Message) {
if r.checkRateLimit(in) {
return rateLimitReply, nil
}
cmd, _ := parseCmd(strings.TrimSpace(in.Message.Text), r.gatewayName)
+49 -3
View File
@@ -68,9 +68,11 @@ func TestRouteNoLimiterConfiguredNeverBlocks(t *testing.T) {
}
// TestRouteEmptySenderIDNeverLimited pins the deliberate fail-open for
// channels (webhook routes with no configured path identity, e.g.) that
// have no stable per-sender identity to charge: there is no shared key to
// throttle everyone under, so they are left unlimited rather than blocked.
// channels that have no stable per-sender identity to charge and no key of
// their own to budget against: there is no shared key to throttle everyone
// under, so they are left unlimited rather than blocked. A channel that has
// a stable source but no per-person identity (a webhook route) sets
// Inbound.BudgetKey instead -- see TestRouteBudgetKeyLimitsWithoutSenderID.
func TestRouteEmptySenderIDNeverLimited(t *testing.T) {
r := NewRouter(nil, fakeLLM, "test")
r.Limiter = ratelimit.New(time.Minute, 1)
@@ -86,6 +88,50 @@ func TestRouteEmptySenderIDNeverLimited(t *testing.T) {
}
}
// TestRouteBudgetKeyLimitsWithoutSenderID pins the split between a message's
// per-person identity and the key it is rate limited against. A webhook has
// no person to identify, so SenderID stays empty, but its route is still a
// bounded, operator-controlled source that must keep its budget -- otherwise
// clearing SenderID would silently exempt every webhook route from the
// limiter config.RateLimitConfig documents.
func TestRouteBudgetKeyLimitsWithoutSenderID(t *testing.T) {
r := NewRouter(nil, fakeLLM, "test")
r.Limiter = ratelimit.New(time.Minute, 1)
budgeted := func(budgetKey, text string) Inbound {
in := inbound("chat-1", text)
in.BudgetKey = budgetKey
return in
}
reply, err := r.Route(context.Background(), budgeted("/hook", "hello"))
if err != nil {
t.Fatalf("Route: %v", err)
}
if reply != "llm: hello" {
t.Fatalf("first message reply = %q, want it to reach the LLM", reply)
}
reply, err = r.Route(context.Background(), budgeted("/hook", "hello again"))
if err != nil {
t.Fatalf("Route: %v", err)
}
if reply != rateLimitReply {
t.Fatalf("second message reply = %q, want the rate-limit reply", reply)
}
// A different route is a different source, so it is unaffected by the
// first route's spent budget -- the same per-source property
// TestRouteRateLimitIsPerSender pins for real senders.
reply, err = r.Route(context.Background(), budgeted("/other", "hello"))
if err != nil {
t.Fatalf("Route: %v", err)
}
if reply != "llm: hello" {
t.Fatalf("other route reply = %q, want it unaffected by /hook's budget", reply)
}
}
// TestRouteStreamLocalCommandChargesExactlyOnce pins RouteStream's local
// command fallthrough (into route, not Route) against double-charging the
// budget: a status query must consume the same one unit whether it goes
@@ -116,6 +116,18 @@ func TestWireValuesPreserveHistoryAndMedia(t *testing.T) {
if got := eventValue(eventProto(event)); !reflect.DeepEqual(got, event) {
t.Fatalf("event round trip: %+v", got)
}
// Transport-only inbound context rides alongside the record and must
// survive the hop: Page reaches the system prompt, and BudgetKey is what
// the Gateway charges the message against when the channel has no
// per-person SenderID to charge (a webhook route).
in := gateway.Inbound{
Message: messaging.Message{ConversationID: messaging.ConversationID{ChannelID: "/hook"}, Role: messaging.RoleUser, Text: "hi"},
Page: "/tasks",
BudgetKey: "/hook",
}
if got := inboundValue(inboundProto(in)); !reflect.DeepEqual(got, in) {
t.Fatalf("inbound round trip = %+v, want %+v", got, in)
}
if got := inboundValue(inboundProto(gateway.Inbound{})); !got.Message.At.IsZero() {
t.Fatalf("zero time became %v", got.Message.At)
}
+4 -3
View File
@@ -55,11 +55,12 @@ func storedValue(v *pb.Message) messaging.Message {
}
// inboundProto renders a channel message and its transport context in wire
// shape. Page rides along; the record's role does not, for the reason
// storedProto gives.
// shape. Page and BudgetKey ride along; the record's role does not, for the
// reason storedProto gives.
func inboundProto(v messaging.Inbound) *pb.Message {
m := storedProto(v.Message)
m.Page = v.Page
m.BudgetKey = v.BudgetKey
return m
}
@@ -73,7 +74,7 @@ func inboundValue(v *pb.Message) messaging.Inbound {
}
msg := storedValue(v)
msg.Role = messaging.RoleUser
return messaging.Inbound{Message: msg, Page: v.Page}
return messaging.Inbound{Message: msg, Page: v.Page, BudgetKey: v.BudgetKey}
}
func toolProto(v messaging.ToolCallEvent) *pb.ToolCall {
@@ -358,7 +358,12 @@ func TestPassSkipsSessionsWithoutASingleParticipant(t *testing.T) {
wantReason string
}{
{
name: "zero senders: a dashboard session carries no per-person identity",
// Both producers are pinned by their own packages: the webhook
// clears SenderID and carries the route in Inbound.BudgetKey
// (internal/channels/webhook), the dashboard never sets one.
// Either way the session arrives here with nothing that names a
// person, which is the input this case pins.
name: "zero senders: a dashboard or webhook session carries no per-person identity",
messages: []curator.ConversationMessage{{Role: "user", Content: "hello"}},
wantReason: "no single participant: 0 distinct sender(s), 1 unidentified user message(s)",
},
+7
View File
@@ -49,6 +49,13 @@ message Message {
string text = 6;
string page = 7;
google.protobuf.Timestamp at = 8;
// budget_key is the source an inbound message is charged against by the
// Gateway's inbound rate limiter, for a channel that has no per-person
// sender id but does have a stable, operator-controlled source of its own
// -- a webhook's configured route path. Transport-only: a channel frontend
// sets it on inbound and it is never persisted, exactly like page. Empty
// means the message is not rate limited.
string budget_key = 9;
}
message ToolCall {
string id = 1;