diff --git a/README.md b/README.md index 3a5091f..4a3968e 100644 --- a/README.md +++ b/README.md @@ -84,7 +84,8 @@ flowchart TD docker compose up --build ``` -Open (set `NEXUS_PORT` to use another port). Workspace code: `northwind`. For the English UI, +Open (set `NEXUS_PORT` to use another port; `NEXUS_SUBNET` if its network `10.213.47.0/24` +clashes with one you have, and run `docker compose down` once after changing it). Workspace code: `northwind`. For the English UI, open : the choice is kept for the next pages. | Who | Email | Password | Sees | @@ -242,8 +243,6 @@ on this repository's Security tab. - **Open issues that matter:** - [#18](https://github.com/doxuta/nexus/issues/18): a record the rep can read but not edit answers `PUT` with 404, not 403. - - [#22](https://github.com/doxuta/nexus/issues/22): `/mcp` has no rate limit and no cap on turns per thread, and its - tool filter is a naming rule. - [#23](https://github.com/doxuta/nexus/issues/23): a table that is still hidden can be reached through N-N links and `?expand` with a crafted call and a granted role, and `PUT /admin/roles/:id` carries no version. diff --git a/SECURITY.md b/SECURITY.md index aa89a4c..e33c063 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -48,7 +48,14 @@ advisory. - An `nxm_` key is stored only as a hash ([`internal/auth/mcp_token.go:12-28`]). It is refused when revoked or expired, when the workspace is retired or suspended, or when its user is no longer an active builder ([`internal/services/mcp_token_service.go:175-233`]). Logout-all and a password change revoke it - ([`internal/services/auth_service_extra.go:202-222`]). + ([`internal/services/auth_service_extra.go:202-222`]). Lookups of `nxm_` keys not yet seen working are throttled + per IP with the `nxk_` budget, and a working key has its own request budget + ([`internal/middleware/mcp_ratelimit.go`](nexus-platform/internal/middleware/mcp_ratelimit.go)). Every per-IP + brake reads the client from X-Forwarded-For only when the peer is in `TRUSTED_PROXY_CIDRS`; behind a proxy, set + it to the proxy's network, or every client shares the proxy's bucket. The one-command demo sets it to its own + network ([`docker-compose.yml`](docker-compose.yml)). A key's thread + takes at most 200 turns and one proposal at most 256 KiB + ([`internal/mcpserver/mcpserver.go`](nexus-platform/internal/mcpserver/mcpserver.go)). - **`/mcp` and `/api/v1` are separate.** `/mcp` is mounted outside `/api/v1`, with its own bearer ([`cmd/server/main.go:1516-1518`]). `/api/v1` refuses an `nxm_` key ([`internal/services/api_key_service.go:496-500`]). `/mcp` answers an `nxk_` key with 403 and any other non-`nxm_` credential with 401 @@ -112,9 +119,6 @@ session ([`nexus-web/lib/aiApply.ts:1-5`]), and a draft-class change then needs - **Access follow-ups ([#23]).** A hidden-new table is still reachable through N-N `Link` and `ListLinked` and through `?expand`, with a crafted call and an approved grant. `PUT /admin/roles/:id` is unversioned. -- **MCP follow-ups ([#22]).** `/mcp` has no rate limit, no brake on failed key lookups, and no cap on turns per thread. - The MCP tool filter is a naming rule, `propose_field` judges a dependent picklist against the published model, and - the MCP note misdescribes an access card. - **404 instead of 403 ([#18]).** A record the rep can read but not edit answers `PUT` with 404. Existence is not leaked, but the reason is misstated. - **The cutoff's second.** Metadata timestamps have second precision. A version's cutoff names the newest definition @@ -192,5 +196,4 @@ session ([`nexus-web/lib/aiApply.ts:1-5`]), and a draft-class change then needs [#18]: https://github.com/doxuta/nexus/issues/18 [#13]: https://github.com/doxuta/nexus/issues/13 [#19]: https://github.com/doxuta/nexus/issues/19 -[#22]: https://github.com/doxuta/nexus/issues/22 [#23]: https://github.com/doxuta/nexus/issues/23 diff --git a/docker-compose.yml b/docker-compose.yml index ca2b52f..e7e2ce8 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -54,6 +54,10 @@ services: BOOTSTRAP_ADMIN_PASSWORD: ${NEXUS_ADMIN_PASS:-Demo-Admin-2026!} BOOTSTRAP_ADMIN_NAME: Demo Builder BOOTSTRAP_PLATFORM_OPERATOR: "true" + # Every request reaches the API through Caddy, so without this the per-IP brakes (login, SSO, failed nxk_ + # and nxm_ lookups) would see Caddy's address for every client and share ONE bucket. The API trusts + # X-Forwarded-For only from this network (Caddy writes it); the network's subnet is fixed below. + TRUSTED_PROXY_CIDRS: ${TRUSTED_PROXY_CIDRS:-${NEXUS_SUBNET:-10.213.47.0/24}} AI_ENABLED: ${AI_ENABLED:-false} AI_GATEWAY_BASE_URL: ${AI_GATEWAY_BASE_URL:-} AI_GATEWAY_API_KEY: ${AI_GATEWAY_API_KEY:-} @@ -102,5 +106,13 @@ services: volumes: - ./deploy/Caddyfile.local:/etc/caddy/Caddyfile:ro +# A fixed subnet, so TRUSTED_PROXY_CIDRS (api) can name it. NEXUS_SUBNET=… if it clashes with a network you have; +# after changing it (or pulling this file over an older stack), `docker compose down` once recreates the network. +networks: + default: + ipam: + config: + - subnet: ${NEXUS_SUBNET:-10.213.47.0/24} + volumes: mysql-data: diff --git a/nexus-platform/.env.example b/nexus-platform/.env.example index d4a9378..eaca80e 100644 --- a/nexus-platform/.env.example +++ b/nexus-platform/.env.example @@ -9,6 +9,11 @@ PORT=8080 # on :3000 (`preview_start nexus-web`). Comma-separated for more than one origin. CORS_ALLOWED_ORIGINS=http://localhost:3000 +# Behind a reverse proxy (Caddy), the networks it reaches the API from, comma-separated. Only these may +# vouch for X-Forwarded-For; empty = the direct peer is the client. Behind a proxy and empty, the per-IP +# brakes (login, SSO, failed nxk_/nxm_ lookups) see one client: the proxy. docker-compose.yml sets it. +# TRUSTED_PROXY_CIDRS=10.213.47.0/24 + # MySQL 8 DSN (Go format). Matches docker-compose's local dev DB. REQUIRED — the server refuses to # start without it (there is no built-in default). loc=UTC: the DB stores timestamps in UTC, and # loc=Local on a +07 machine labels them with the local offset → every instant 7h off (R2-03). diff --git a/nexus-platform/cmd/server/main.go b/nexus-platform/cmd/server/main.go index d4df14e..b5d00da 100644 --- a/nexus-platform/cmd/server/main.go +++ b/nexus-platform/cmd/server/main.go @@ -1518,8 +1518,16 @@ func main() { }) }) // MCP (issue #3): agents propose, humans dispose. Outside /api/v1: its own bearer (nxm_ tokens - // only, refused everywhere else) and the SDK's stateless streamable HTTP transport. - r.Any("/mcp", gin.WrapH(mcpserver.New(mcpTokenSvc, aiAgent, aiSessionStore, tenantFreeze, logger))) + // only, refused everywhere else) and the SDK's stateless streamable HTTP transport. Issue #22: the + // API's brakes in front of it — an IP's lookups of tokens not yet seen working get the API-key + // brake's budget, each working token the data plane's per-key budget. + mcpLimiter := middleware.MCPRateLimit(middleware.MCPRateLimitConfig{ + ProbeMax: cfg.APIKeyProbeMaxPerMin, + KeyMax: cfg.DataRateLimitPerMin, + Window: time.Minute, + TrustedProxyCIDRs: cfg.TrustedProxyCIDRs, + }) + r.Any("/mcp", mcpLimiter, gin.WrapH(mcpserver.New(mcpTokenSvc, aiAgent, aiSessionStore, tenantFreeze, logger))) // API v1 routes. RegisterAPIRoutes is the single wiring point shared with the integration // tests: it mounts the PUBLIC /auth/* endpoints, then a PROTECTED sub-group fronted by diff --git a/nexus-platform/cmd/server/main_wiring_test.go b/nexus-platform/cmd/server/main_wiring_test.go index d9e48c4..52b309e 100644 --- a/nexus-platform/cmd/server/main_wiring_test.go +++ b/nexus-platform/cmd/server/main_wiring_test.go @@ -16,8 +16,11 @@ import ( "go/printer" "go/token" "os" + "regexp" "strings" "testing" + + "nexus/platform/internal/config" ) // hardeningOptions maps each RegisterAPIRoutes option main.go must pass to the source its argument @@ -236,3 +239,46 @@ func isLiteral(e ast.Expr) bool { _, ok := e.(*ast.BasicLit) return ok } + +// TestMainWiresTheMCPBrake (issue #22): /mcp sits outside /api/v1, so none of RegisterAPIRoutes' +// limiters reach it. Its own brake must sit in front of the handler on the route itself, with its +// budgets and the trusted proxies read from config (a zero budget switches that brake off). +func TestMainWiresTheMCPBrake(t *testing.T) { + src, err := os.ReadFile("main.go") + if err != nil { + t.Fatalf("read main.go: %v", err) + } + flat := strings.Join(strings.Fields(string(src)), "") + for _, want := range []string{ + "mcpLimiter:=middleware.MCPRateLimit(middleware.MCPRateLimitConfig{", + "ProbeMax:cfg.APIKeyProbeMaxPerMin,", + "KeyMax:cfg.DataRateLimitPerMin,", + "TrustedProxyCIDRs:cfg.TrustedProxyCIDRs,", + `r.Any("/mcp",mcpLimiter,gin.WrapH(mcpserver.New(`, + } { + if !strings.Contains(flat, want) { + t.Errorf("main.go lost %q — /mcp would answer guesses and floods unbraked", want) + } + } +} + +// TestComposeTrustsItsOwnNetwork (issue #22): in the one-command demo every request reaches the API through +// Caddy, so the per-IP brakes key on X-Forwarded-For only if TRUSTED_PROXY_CIDRS names the compose network. +// Its default must be the network's fixed subnet, and parse. +func TestComposeTrustsItsOwnNetwork(t *testing.T) { + src, err := os.ReadFile("../../../docker-compose.yml") + if err != nil { + t.Fatalf("read docker-compose.yml: %v", err) + } + trusted := regexp.MustCompile(`TRUSTED_PROXY_CIDRS: \$\{TRUSTED_PROXY_CIDRS:-\$\{NEXUS_SUBNET:-([^}]+)\}\}`).FindSubmatch(src) + subnet := regexp.MustCompile(`subnet: \$\{NEXUS_SUBNET:-([^}]+)\}`).FindSubmatch(src) + if trusted == nil || subnet == nil { + t.Fatalf("docker-compose.yml lost the api's TRUSTED_PROXY_CIDRS or the network's fixed subnet: every client behind Caddy shares one bucket") + } + if string(trusted[1]) != string(subnet[1]) { + t.Fatalf("TRUSTED_PROXY_CIDRS defaults to %s but the network is %s", trusted[1], subnet[1]) + } + if nets, skipped := config.ParseTrustedProxyCIDRs(string(trusted[1])); len(nets) != 1 || len(skipped) != 0 { + t.Fatalf("TRUSTED_PROXY_CIDRS default %s does not parse: %v", trusted[1], skipped) + } +} diff --git a/nexus-platform/internal/ai/tools.go b/nexus-platform/internal/ai/tools.go index e86ab3f..d10d92d 100644 --- a/nexus-platform/internal/ai/tools.go +++ b/nexus-platform/internal/ai/tools.go @@ -1106,8 +1106,9 @@ func (e *toolExecutor) proposeEntity(ctx context.Context, argsJSON string) strin // config-time validator) before buffering — same parity guarantee as proposeEntity. A name the // table already has — live, drafted with the table, or proposed earlier this turn (pendingFields) — // is refused here with the apply path's own code (FIELD_ALREADY_EXISTS), as proposeEntity refuses a -// taken table name (#30 item 3). A table that is neither live nor drafted is left to Apply -// (ENTITY_NOT_FOUND), as before. +// taken table name (#30 item 3). A table that is neither live in this tenant nor drafted (this turn, +// or earlier in an MCP thread) is refused with Apply's ENTITY_NOT_FOUND, as propose_layout does +// (issue #22): no card is filed for a table the tenant does not have. func (e *toolExecutor) proposeField(ctx context.Context, argsJSON string) string { var a proposedField // proposedField only carries the field attributes; entity is a sibling key on the same object. @@ -1126,7 +1127,10 @@ func (e *toolExecutor) proposeField(ctx context.Context, argsJSON string) string return toolErr("%s: %s", code, msg) } entity, live, fields, err := e.pendingFields(ctx, withEntity.Entity) - if err != nil && !errors.Is(err, metadata.ErrEntityNotFound) { + if errors.Is(err, metadata.ErrEntityNotFound) { + return toolErr("ENTITY_NOT_FOUND: entity %q không tồn tại và cũng chưa được propose_entity trong lượt này — propose_entity trước rồi propose_field trong CÙNG lượt", withEntity.Entity) + } + if err != nil { return toolErr("PROPOSE_FIELD_FAILED: %v", err) } if i := slices.IndexFunc(fields, func(f metadata.FieldDefinition) bool { return f.Name == a.Name }); i >= 0 { diff --git a/nexus-platform/internal/ai/tools_field_options_test.go b/nexus-platform/internal/ai/tools_field_options_test.go index e7370cf..f51b58e 100644 --- a/nexus-platform/internal/ai/tools_field_options_test.go +++ b/nexus-platform/internal/ai/tools_field_options_test.go @@ -132,40 +132,40 @@ func TestTools_ProposeField_OptionsValidationParity(t *testing.T) { // ---- AI-TOOL-COVERAGE (Wave 4.6): the advanced types now on the AI surface ---- { name: "auto_number (số chứng từ) → buffered, prefix/padding giữ nguyên", - args: `{"entity":"invoices","name":"invoice_no","label":"Số hoá đơn","fieldType":"auto_number", + args: `{"entity":"patients","name":"invoice_no","label":"Số hoá đơn","fieldType":"auto_number", "options":{"prefix":"HĐ-","padding":5}}`, wantOpts: map[string]any{"prefix": "HĐ-", "padding": float64(5)}, }, { name: "formula (tổng tính toán) → buffered", - args: `{"entity":"invoice_lines","name":"line_total","label":"Thành tiền","fieldType":"formula", + args: `{"entity":"patients","name":"line_total","label":"Thành tiền","fieldType":"formula", "options":{"formula":"quantity * unit_price","resultType":"currency"}}`, wantOpts: map[string]any{"formula": "quantity * unit_price", "resultType": "currency"}, }, { name: "formula thiếu biểu thức → REJECT config-time", - args: `{"entity":"invoices","name":"bad_f","label":"Bad","fieldType":"formula","options":{}}`, + args: `{"entity":"patients","name":"bad_f","label":"Bad","fieldType":"formula","options":{}}`, wantCode: "FIELD_FORMULA_INVALID", }, // ---- ai-builder-field-type-parity: user + polymorphic_relation on the AI surface ---- { name: "user (người phụ trách) không options → buffered", - args: `{"entity":"crm_tasks","name":"assignee","label":"Người phụ trách","fieldType":"user"}`, + args: `{"entity":"patients","name":"assignee","label":"Người phụ trách","fieldType":"user"}`, }, { name: "polymorphic_relation với targetEntities → buffered, đích giữ nguyên", - args: `{"entity":"crm_tasks","name":"related_to","label":"Liên quan tới","fieldType":"polymorphic_relation", + args: `{"entity":"patients","name":"related_to","label":"Liên quan tới","fieldType":"polymorphic_relation", "options":{"targetEntities":["crm_accounts","crm_contacts"]}}`, wantOpts: map[string]any{"targetEntities": []any{"crm_accounts", "crm_contacts"}}, }, { name: "polymorphic_relation thiếu targetEntities → FIELD_POLYMORPHIC_NO_TARGETS (không để tới Apply mới 422)", - args: `{"entity":"crm_tasks","name":"related_to","label":"Liên quan tới","fieldType":"polymorphic_relation"}`, + args: `{"entity":"patients","name":"related_to","label":"Liên quan tới","fieldType":"polymorphic_relation"}`, wantCode: "FIELD_POLYMORPHIC_NO_TARGETS", }, { name: "polymorphic_relation tên > 21 ký tự → FIELD_POLYMORPHIC_NAME_TOO_LONG", - args: `{"entity":"crm_tasks","name":"related_record_targets","label":"Liên quan","fieldType":"polymorphic_relation", + args: `{"entity":"patients","name":"related_record_targets","label":"Liên quan","fieldType":"polymorphic_relation", "options":{"targetEntities":["crm_accounts"]}}`, wantCode: "FIELD_POLYMORPHIC_NAME_TOO_LONG", }, diff --git a/nexus-platform/internal/ai/tools_field_scope_test.go b/nexus-platform/internal/ai/tools_field_scope_test.go new file mode 100644 index 0000000..477881b --- /dev/null +++ b/nexus-platform/internal/ai/tools_field_scope_test.go @@ -0,0 +1,92 @@ +package ai + +import ( + "context" + "slices" + "strings" + "testing" + + "go.uber.org/zap" + + "nexus/platform/internal/config" + "nexus/platform/internal/metadata" + "nexus/platform/internal/metaversion" +) + +// Issue #22 item 1: propose_field judges a dependent picklist against the model the CALLER reads (on a +// delivered project, the builder's drafts), and files no card for a table its tenant does not have. + +// draftOverlayReader shows the builder's unpublished edit of tickets.status (a value "hold") only to a +// ctx that carries a ReadDraft Caller, as services.DraftFieldRepo does on a delivered project. +type draftOverlayReader struct{ *fakeMetaReader } + +func (r draftOverlayReader) ListFields(ctx context.Context, tenantID, entityID string) ([]metadata.FieldDefinition, error) { + fields, err := r.fakeMetaReader.ListFields(ctx, tenantID, entityID) + if c, ok := metaversion.CallerFrom(ctx); err != nil || !ok || !c.ReadDraft { + return fields, err + } + out := slices.Clone(fields) + for i := range out { + if out[i].Name == "status" { + draft := `{"values":["open","closed","hold"]}` + out[i].Options = &draft + } + } + return out, nil +} + +const holdReason = `{"entity":"tickets","name":"hold_reason","label":"Lý do chờ","fieldType":"picklist", + "options":{"values":["parts","other"],"controllingField":"status","dependentValues":{"hold":["parts"]}}}` + +func TestTools_ProposeField_SiblingsAreTheCallersDraft(t *testing.T) { + builder := metaversion.WithCaller(context.Background(), metaversion.Caller{UserID: "u-b", TenantID: "tenant-A", HomeTenantID: "tenant-A", IsBuilder: true, ReadDraft: true}) + reader := draftOverlayReader{editFixtureReader()} + + t.Run("in-app turn", func(t *testing.T) { + e := &toolExecutor{reader: reader, tenantID: "tenant-A"} + if ok, _ := parseToolResult(t, e.execute(builder, "propose_field", holdReason)); !ok || len(e.draft) != 1 { + t.Fatalf("keyed on the builder's draft value: want buffered, got %v (draft %d)", ok, len(e.draft)) + } + // The control: without the builder's Caller the published model has no "hold". + e = &toolExecutor{reader: reader, tenantID: "tenant-A"} + if res := e.execute(context.Background(), "propose_field", holdReason); !strings.Contains(res, "FIELD_DEPENDENT_PICKLIST_INVALID") { + t.Fatalf("the published model must refuse it: %s", res) + } + }) + + t.Run("one MCP call (RunTool)", func(t *testing.T) { + agent := NewAIBuilderAgent(config.AIConfig{}, nil, reader, nil, nil, zap.NewNop()) + res, added := agent.RunTool(builder, "tenant-A", "sess-1", nil, "propose_field", holdReason) + if ok, _ := parseToolResult(t, res); !ok || len(added) != 1 { + t.Fatalf("keyed on the builder's draft value: want one proposal, got %s", res) + } + }) +} + +func TestTools_ProposeField_RefusesATableNotInTheTenant(t *testing.T) { + note := func(entity string) string { + return `{"entity":"` + entity + `","name":"note","label":"Ghi chú","fieldType":"text"}` + } + agent := NewAIBuilderAgent(config.AIConfig{}, nil, editFixtureReader(), nil, nil, zap.NewNop()) + // "invoices" is tenant-B's table: it must read as missing to tenant-A, as any unknown name does. + for _, entity := range []string{"ghosts", "invoices"} { + e := &toolExecutor{reader: editFixtureReader(), tenantID: "tenant-A"} + if res := e.execute(context.Background(), "propose_field", note(entity)); !strings.Contains(res, "ENTITY_NOT_FOUND") || len(e.draft) != 0 { + t.Errorf("in-app propose_field on %q: %s (draft %d); want ENTITY_NOT_FOUND and no card", entity, res, len(e.draft)) + } + if res, added := agent.RunTool(context.Background(), "tenant-A", "sess-1", nil, "propose_field", note(entity)); !strings.Contains(res, "ENTITY_NOT_FOUND") || len(added) != 0 { + t.Errorf("MCP propose_field on %q: %s (%d added); want ENTITY_NOT_FOUND and no card", entity, res, len(added)) + } + } + + // A table proposed earlier — this turn, or earlier in the MCP thread (prior) — is not missing. + e := &toolExecutor{reader: editFixtureReader(), tenantID: "tenant-A"} + e.execute(context.Background(), "propose_entity", `{"name":"ghosts","label":"Ma","fields":[{"name":"title","label":"Tên","fieldType":"text"}]}`) + if ok, _ := parseToolResult(t, e.execute(context.Background(), "propose_field", note("ghosts"))); !ok { + t.Fatal("a table drafted this turn must take a field") + } + prior := []DraftItem{{Kind: "entity", Entity: &DraftEntity{Name: "ghosts", Label: "Ma"}}} + if res, added := agent.RunTool(context.Background(), "tenant-A", "sess-1", prior, "propose_field", note("ghosts")); len(added) != 1 { + t.Fatalf("a table the thread proposed earlier must take a field: %s", res) + } +} diff --git a/nexus-platform/internal/ai/tools_readonly_pin_test.go b/nexus-platform/internal/ai/tools_readonly_pin_test.go new file mode 100644 index 0000000..daaca63 --- /dev/null +++ b/nexus-platform/internal/ai/tools_readonly_pin_test.go @@ -0,0 +1,233 @@ +package ai + +import ( + "bytes" + "go/ast" + "go/parser" + "go/printer" + "go/token" + "path/filepath" + "reflect" + "regexp" + "slices" + "strings" + "testing" +) + +// Issue #22 item 3: MCP (internal/mcpserver) and the in-app builder run every tool through toolExecutor, +// and "agents propose, humans dispose" holds only while nothing the executor can reach writes. The tool +// names are pinned elsewhere (read_* / propose_* only); this pins what the executor is BUILT from: every +// interface it can call is a narrow read interface, and it holds no func, channel or concrete service. + +// readVerbs are the method names an executor dependency may have. A new method fails the pin until a +// human reads it and adds it here: Get*/List*/Load*/Find* read; the rest are named one by one. +var readVerbs = regexp.MustCompile(`^(Get|List|Load|Find)[A-Z]|^Get$|^(Authorize|HeadCutoff|ColumnExists|RefEntity|AccessProbes|PrivilegedHolders)$`) + +// writeWords may not appear anywhere in a read method's name: GetOrCreate, FindOrCreate or ListAndPurge +// start like a read and then write. +var writeWords = []string{"Create", "Update", "Delete", "Insert", "Upsert", "Save", "Set", "Put", "Write", "Apply", + "Publish", "Revoke", "Grant", "Remove", "Purge", "Touch", "Append", "Mark", "Settle", "Exec", "Execute", "Store", + "Add", "Drop", "Reset", "Clear", "Bump", "Commit", "Rollback", "Send", "Enqueue", "Post", "Patch", "Replace", + "Restore", "Install", "Import", "Move", "Rename", "Assign"} + +var camelWords = regexp.MustCompile(`[A-Z][a-z0-9]*`) + +func isReadMethod(name string) bool { + if !readVerbs.MatchString(name) { + return false + } + return !slices.ContainsFunc(camelWords.FindAllString(name, -1), func(w string) bool { return slices.Contains(writeWords, w) }) +} + +// executorRoots are the types the executor reaches: its own fields, and the probes it gets by +// type-asserting its reader to AccessProbeCarrier (the only interface it asserts to, pinned below). +var executorRoots = []reflect.Type{ + reflect.TypeOf(toolExecutor{}), + reflect.TypeOf((*AccessProbeCarrier)(nil)).Elem(), + reflect.TypeOf(AccessProbes{}), +} + +func TestToolExecutor_ReachesReadOnlyDependenciesOnly(t *testing.T) { + for _, bad := range readOnlyViolations(executorRoots) { + t.Error(bad) + } +} + +// The pin must catch what it guards against: a field or a probe that can write. +func TestToolExecutor_ReadOnlyPinCatchesAWriter(t *testing.T) { + type writer interface { + GetEntityByName() error + CreateEntity() error + GetOrCreateEntity() error + FindOrCreateRole() error + ListAndPurgeDrafts() error + ListFieldsIncludingDeleted() error + } + type withWriter struct { + reader MetadataReader + probes *struct{ Store writer } + hook func() + } + got := strings.Join(readOnlyViolations([]reflect.Type{reflect.TypeOf(withWriter{})}), "\n") + for _, want := range []string{"CreateEntity", "GetOrCreateEntity", "FindOrCreateRole", "ListAndPurgeDrafts", "func"} { + if !strings.Contains(got, want) { + t.Errorf("the pin let %q through: %s", want, got) + } + } + if strings.Contains(got, "GetEntityByName") || strings.Contains(got, "ListFieldsIncludingDeleted") { + t.Errorf("a read method was reported: %s", got) + } +} + +// The executor reaches further dependencies only by asserting a value to another type, which reflection +// cannot see. So the package's source is read: every type assertion or type-switch case to anything but +// plain data (basic types, maps, slices, any) must be listed here, and an interface the executor reaches +// that way must also be a root above. +var allowedAssertions = map[string]string{ + "AccessProbeCarrier": "the reader's probes: a root of the pin", + "UserTokenLedger": "the budget guard's ledger (agent loop), not reachable from toolExecutor", + "*replayer": "the cassette gateway (cassette.go), not reachable from toolExecutor", +} + +func TestToolExecutor_TypeAssertionsArePinned(t *testing.T) { + files, err := filepath.Glob("*.go") + if err != nil { + t.Fatal(err) + } + for _, f := range files { + if strings.HasSuffix(f, "_test.go") { + continue + } + for _, bad := range assertionViolations(t, f, nil) { + t.Error(bad) + } + } +} + +// The scan must catch the shapes a regex missed: a package-qualified or pointer target, a chained +// assertion on an embedded reader, a type switch. +func TestToolExecutor_TypeAssertionScanCatchesEveryShape(t *testing.T) { + src := `package ai +func (e *toolExecutor) x() { + _, _ = e.reader.(AccessProbeCarrier) + _, _ = e.reader.(services.MetadataWriter) + _ = e.reader.(*readerWithAccessProbes).MetadataReader.(MetadataReader) + r := e.reader + switch r.(type) { + case interface{ CreateEntity() error }, nil: + } + _, _ = e.args.(map[string]any) + _, _ = e.args.(string) +}` + got := strings.Join(assertionViolations(t, "sample.go", []byte(src)), "\n") + for _, want := range []string{"services.MetadataWriter", "*readerWithAccessProbes", "MetadataReader", "CreateEntity"} { + if !strings.Contains(got, want) { + t.Errorf("the scan let an assertion to %s through: %s", want, got) + } + } + for _, ok := range []string{"AccessProbeCarrier", "map[string]any", "string", "nil"} { + if strings.Contains(got, "to "+ok+":") { + t.Errorf("the scan reported %s: %s", ok, got) + } + } +} + +// assertionViolations parses one file (src, or the file at name when src is nil) and reports each type +// assertion or type-switch case whose target is neither plain data nor in allowedAssertions. +func assertionViolations(t *testing.T, name string, src []byte) []string { + t.Helper() + fset := token.NewFileSet() + var source any // a nil []byte would parse as an empty file + if src != nil { + source = src + } + file, err := parser.ParseFile(fset, name, source, 0) + if err != nil { + t.Fatalf("parse %s: %v", name, err) + } + render := func(n ast.Node) string { + var b bytes.Buffer + _ = printer.Fprint(&b, fset, n) + return b.String() + } + var out []string + check := func(at token.Pos, target ast.Expr) { + if isPlainData(target) { + return + } + if typ := render(target); allowedAssertions[typ] == "" { + out = append(out, fset.Position(at).String()+" asserts to "+typ+": list it in allowedAssertions, and add an interface the executor reaches to executorRoots") + } + } + ast.Inspect(file, func(n ast.Node) bool { + switch n := n.(type) { + case *ast.TypeAssertExpr: + if n.Type != nil { // nil = the x.(type) of a switch, judged by its cases below + check(n.Pos(), n.Type) + } + case *ast.TypeSwitchStmt: + for _, c := range n.Body.List { + for _, target := range c.(*ast.CaseClause).List { + check(target.Pos(), target) + } + } + } + return true + }) + return out +} + +// isPlainData reports a target that carries no behaviour: a predeclared type, a map, a slice or an array +// of plain data, or the empty interface. +func isPlainData(e ast.Expr) bool { + switch e := e.(type) { + case *ast.Ident: + return slices.Contains([]string{"any", "nil", "string", "bool", "error", "byte", "rune", "int", "int8", "int16", "int32", + "int64", "uint", "uint8", "uint16", "uint32", "uint64", "float32", "float64"}, e.Name) + case *ast.MapType: + return isPlainData(e.Key) && isPlainData(e.Value) + case *ast.ArrayType: + return isPlainData(e.Elt) + case *ast.InterfaceType: + return len(e.Methods.List) == 0 + } + return false +} + +// readOnlyViolations walks the types reachable from roots and reports every method that is not a read +// verb, and every func or channel (code the executor could call that the pin cannot read). +func readOnlyViolations(roots []reflect.Type) []string { + var out []string + seen := map[reflect.Type]bool{} + var walk func(path string, t reflect.Type) + walk = func(path string, t reflect.Type) { + if seen[t] { + return + } + seen[t] = true + switch t.Kind() { + case reflect.Interface: + for i := range t.NumMethod() { + if m := t.Method(i); !isReadMethod(m.Name) { + out = append(out, path+" ("+t.String()+") has "+m.Name+": not a read") + } + } + case reflect.Func, reflect.Chan, reflect.UnsafePointer: + out = append(out, path+" is a "+t.Kind().String()+": the executor must hold read interfaces, not code") + case reflect.Pointer, reflect.Slice, reflect.Array: + walk(path, t.Elem()) + case reflect.Map: + walk(path, t.Key()) + walk(path, t.Elem()) + case reflect.Struct: + for i := range t.NumField() { + f := t.Field(i) + walk(path+"."+f.Name, f.Type) + } + } + } + for _, r := range roots { + walk(r.Name(), r) + } + return out +} diff --git a/nexus-platform/internal/handlers/mcp_integration_test.go b/nexus-platform/internal/handlers/mcp_integration_test.go index cc7e3c0..a976ed8 100644 --- a/nexus-platform/internal/handlers/mcp_integration_test.go +++ b/nexus-platform/internal/handlers/mcp_integration_test.go @@ -19,6 +19,7 @@ import ( "strings" "sync" "testing" + "time" "github.com/gin-gonic/gin" "github.com/google/uuid" @@ -96,7 +97,9 @@ func newMCPITRouter(t *testing.T, gdb *gorm.DB, sx *sqlx.DB) mcpITRouter { }, zap.NewNop(), WithLiveSubject(services.NewCachedUserLoader(userRepo, services.DefaultUserClaimTTL)), WithOperatorTier(middleware.RequireBuilderTier(userRepo, zap.NewNop()))) - r.Any("/mcp", gin.WrapH(mcpserver.New(mcpSvc, agent, store, nil, zap.NewNop()))) // as cmd/server/main.go + // as cmd/server/main.go, with the brake at its default budgets (config.go: APIKEY_PROBE_MAX_PER_MIN, DATA_RATE_LIMIT_PER_MIN) + brake := middleware.MCPRateLimit(middleware.MCPRateLimitConfig{ProbeMax: 30, KeyMax: 600, Window: time.Minute}) + r.Any("/mcp", brake, gin.WrapH(mcpserver.New(mcpSvc, agent, store, nil, zap.NewNop()))) return mcpITRouter{r: r, keys: apiKeySvc} } diff --git a/nexus-platform/internal/handlers/mcp_propose_field_integration_test.go b/nexus-platform/internal/handlers/mcp_propose_field_integration_test.go new file mode 100644 index 0000000..8dc2c7c --- /dev/null +++ b/nexus-platform/internal/handlers/mcp_propose_field_integration_test.go @@ -0,0 +1,177 @@ +//go:build integration + +// Issue #22 over a real /mcp on real MySQL. Item 1: propose_field judges a dependent picklist against +// the builder's DRAFT of its parent (a delivered project, read the way cmd/server/main.go's +// aiDraftFieldReader reads fields), and files no card for a table that is not in the token's tenant. +// Item 2: the brake in front of /mcp, judged on the real handler's answers. +// +// Run: go test -tags=integration ./internal/handlers/ -run 'TestMCP_(ProposeField|Brake)' + +package handlers + +import ( + "context" + "encoding/json" + "net/http/httptest" + "strings" + "testing" + "time" + + "github.com/gin-gonic/gin" + "github.com/google/uuid" + "github.com/modelcontextprotocol/go-sdk/mcp" + "go.uber.org/zap" + + "nexus/platform/internal/ai" + "nexus/platform/internal/auth" + "nexus/platform/internal/config" + "nexus/platform/internal/dynrepo" + "nexus/platform/internal/mcpserver" + "nexus/platform/internal/metadata" + "nexus/platform/internal/metaversion" + "nexus/platform/internal/middleware" + "nexus/platform/internal/services" +) + +// draftFieldReader is cmd/server/main.go's aiDraftFieldReader: the registry, with field lists read +// through the draft layer. +type draftFieldReader struct { + *metadata.Repository + fields *services.DraftFieldRepo +} + +func (r draftFieldReader) ListFields(ctx context.Context, tenantID, entityID string) ([]metadata.FieldDefinition, error) { + return r.fields.ListFields(ctx, tenantID, entityID) +} + +func TestMCP_ProposeFieldJudgesTheBuildersDraftAndItsOwnTenant(t *testing.T) { + gdb, sx := a4SetupMigratedDB(t) + ctx := context.Background() + const tenant, other = "ten-mcp-pfield", "ten-mcp-pfother" + builderID := mcpBuilder(t, gdb, tenant, "mcp-pfield") + a4SeedTenant(t, gdb, other, "mcp-pfother", "Other") + entID, statusID := uuid.NewString(), uuid.NewString() + status := `{"values":["open","closed"]}` + for _, row := range []any{ + &metadata.EntityDefinition{ID: entID, TenantID: tenant, Name: "pf_tickets", Label: "Tickets", DataTable: "obj_pf_tickets"}, + &metadata.FieldDefinition{ID: statusID, EntityID: entID, TenantID: tenant, Name: "status", Label: "Status", FieldType: "picklist", Options: &status, FieldOrder: 10}, + // A table of ANOTHER tenant: its name must read as missing to this token. + &metadata.EntityDefinition{ID: uuid.NewString(), TenantID: other, Name: "pf_invoices", Label: "Invoices", DataTable: "obj_pf_invoices"}, + } { + if err := gdb.Create(row).Error; err != nil { + t.Fatalf("seed: %v", err) + } + } + + // Deliver the project, then the builder adds "hold" to status: a draft, not yet the customer's. + meta := metadata.NewRepository(gdb) + reg := metaversion.NewRegistry(services.NewFieldDocAdapter()) + drafts := metaversion.NewDraftRepo(sx, reg) + vers := metaversion.NewVersionRepo(sx) + gate := services.NewDraftGate(vers) + fieldDrafts := services.NewDraftFieldRepo(meta, drafts, gate) + builderCtx := metaversion.WithCaller(ctx, metaversion.Caller{UserID: builderID, TenantID: tenant, HomeTenantID: tenant, IsBuilder: true, ReadDraft: true}) + if _, err := services.NewPublishService(sx, drafts, vers, reg, gate, nil, nil).Baseline(builderCtx, tenant, "first"); err != nil { + t.Fatalf("deliver: %v", err) + } + fieldSvc := services.NewFieldService(dynrepo.New(sx), meta).WithDraftFields(fieldDrafts) + if _, err := fieldSvc.EditField(builderCtx, tenant, services.EditFieldInput{FieldID: statusID, + Options: map[string]any{"values": []any{"open", "closed", "hold"}}}); err != nil { + t.Fatalf("the builder's draft edit: %v", err) + } + var live string + if err := sx.Get(&live, "SELECT CAST(options AS CHAR) FROM sys_fields WHERE id = ?", statusID); err != nil || strings.Contains(live, "hold") { + t.Fatalf("published status = %s (%v); the edit must be a draft", live, err) + } + + agent := ai.NewAIBuilderAgent(config.AIConfig{}, nil, draftFieldReader{meta, fieldDrafts}, nil, nil, zap.NewNop()) + store := ai.NewSessionStore(sx) + mcpSvc := services.NewMCPTokenService(auth.NewMCPTokenRepository(gdb), store, auth.NewUserRepository(gdb)) + _, secret, err := mcpSvc.Issue(ctx, auth.Subject{UserID: builderID, TenantID: tenant, IsAdmin: true}, nil) + if err != nil { + t.Fatalf("issue: %v", err) + } + ts := httptest.NewServer(mcpserver.New(mcpSvc, agent, store, nil, zap.NewNop())) + defer ts.Close() + cs := mcpConnect(t, ts.URL, secret) + + // propose answers "" when the card landed, else the validator's "CODE: message". + propose := func(t *testing.T, args map[string]any) string { + t.Helper() + res, err := cs.CallTool(ctx, &mcp.CallToolParams{Name: "nexus_propose_field", Arguments: args}) + if err != nil { + t.Fatalf("propose_field: %v", err) + } + if !res.IsError { + return "" + } + var env struct{ Error string } + if json.Unmarshal([]byte(mcpText(res)), &env) != nil || env.Error == "" { + return mcpText(res) + } + return env.Error + } + + t.Run("a dependent value keyed on the builder's draft value is accepted", func(t *testing.T) { + if got := propose(t, map[string]any{"entity": "pf_tickets", "name": "hold_reason", "label": "Hold reason", "fieldType": "picklist", + "options": map[string]any{"values": []string{"parts", "other"}, "controllingField": "status", "dependentValues": map[string]any{"hold": []string{"parts"}}}}); got != "" { + t.Fatalf("keyed on the draft value hold: %q; want the card (the builder's model has hold)", got) + } + }) + + t.Run("a table not in the token's tenant gets no card", func(t *testing.T) { + for _, entity := range []string{"pf_invoices", "pf_ghosts"} { + if got := propose(t, map[string]any{"entity": entity, "name": "note", "label": "Note", "fieldType": "text"}); !strings.HasPrefix(got, "ENTITY_NOT_FOUND") { + t.Errorf("propose_field on %s: %q; want ENTITY_NOT_FOUND", entity, got) + } + } + var cards int + if err := sx.Get(&cards, `SELECT COUNT(*) FROM sys_ai_messages WHERE tenant_id = ? AND draft_json IS NOT NULL`, tenant); err != nil || cards != 1 { + t.Fatalf("cards in the thread = %d (%v); want only the accepted one", cards, err) + } + }) +} + +// The brake trusts two answers of the real handler: a 2xx marks a token working, a 401 forgets it. +func TestMCP_BrakeStopsGuessesNotTheWorkingKey(t *testing.T) { + gdb, sx := a4SetupMigratedDB(t) + ctx := context.Background() + const tenant = "ten-mcp-brake" + builderID := mcpBuilder(t, gdb, tenant, "mcp-brake") + store := ai.NewSessionStore(sx) + mcpSvc := services.NewMCPTokenService(auth.NewMCPTokenRepository(gdb), store, auth.NewUserRepository(gdb)) + tok, secret, err := mcpSvc.Issue(ctx, auth.Subject{UserID: builderID, TenantID: tenant, IsAdmin: true}, nil) + if err != nil { + t.Fatalf("issue: %v", err) + } + agent := ai.NewAIBuilderAgent(config.AIConfig{}, nil, metadata.NewRepository(gdb), nil, nil, zap.NewNop()) + gin.SetMode(gin.TestMode) + r := gin.New() + // as cmd/server/main.go, with a small IP budget + r.Any("/mcp", middleware.MCPRateLimit(middleware.MCPRateLimitConfig{ProbeMax: 3, KeyMax: 100, Window: time.Minute}), + gin.WrapH(mcpserver.New(mcpSvc, agent, store, nil, zap.NewNop()))) + + for i, step := range []struct { + credential string + want int + }{ + {secret, 200}, // a real key's first call: the IP's lookup 1 of 3; it works from now on + {"nxm_guess1", 401}, // lookup 2 + {"nxm_guess2", 401}, // lookup 3 + {"nxm_guess3", 429}, // the IP's budget is spent: refused before any lookup + {secret, 200}, // the working key is not the prober + } { + if got := mcpStatus(t, r, step.credential); got != step.want { + t.Fatalf("step %d: %d; want %d", i+1, got, step.want) + } + } + if err := mcpSvc.Revoke(ctx, tenant, builderID, tok.ID); err != nil { + t.Fatalf("revoke: %v", err) + } + if got := mcpStatus(t, r, secret); got != 401 { // the key's own budget, and now forgotten + t.Fatalf("the revoked key: %d; want 401", got) + } + if got := mcpStatus(t, r, secret); got != 429 { // back on the spent IP budget + t.Fatalf("the revoked key again: %d; want 429", got) + } +} diff --git a/nexus-platform/internal/mcpserver/mcpserver.go b/nexus-platform/internal/mcpserver/mcpserver.go index a9650a7..cecef1e 100644 --- a/nexus-platform/internal/mcpserver/mcpserver.go +++ b/nexus-platform/internal/mcpserver/mcpserver.go @@ -48,7 +48,7 @@ type Threads interface { } // instructions is what an MCP client hands its model about this server. -const instructions = `Nexus is a platform for business apps whose apps are metadata: tables (entities), fields, relations, layouts, automation rules, reports, apps and access. These tools read ONE workspace's model and PROPOSE changes to it. A proposal changes nothing: it is saved as a card in the builder's Studio thread, where a human reviews it, applies it to drafts and publishes it. No tool applies, publishes or writes data, so tell the user the change is waiting for review. Read before you propose (nexus_list_entities, nexus_list_fields). Names are snake_case; labels are what users see. A call refused by a validator answers {"ok":false,"error":"CODE: message"}: fix the arguments and call again. Tool descriptions are in Vietnamese.` +const instructions = `Nexus is a platform for business apps whose apps are metadata: tables (entities), fields, relations, layouts, automation rules, reports, apps and access. These tools read ONE workspace's model and PROPOSE changes to it. A proposal changes nothing: it is saved as a card in the builder's Studio thread, where a human reviews and applies it. No tool applies, publishes or writes data, so tell the user the change is waiting for review. Read before you propose (nexus_list_entities, nexus_list_fields). Names are snake_case; labels are what users see. A call refused by a validator answers {"ok":false,"error":"CODE: message"}: fix the arguments and call again. Tool descriptions are in Vietnamese.` type server struct { tokens Verifier @@ -129,8 +129,35 @@ func writeErr(w http.ResponseWriter, status int, code, msg string) { _ = json.NewEncoder(w).Encode(map[string]string{"error": msg, "code": code}) } -// proposedNote follows the result of a proposal: where it went, and that nothing changed yet. -const proposedNote = "Saved as a card in the builder's Studio thread. Nothing has changed: a human reviews the card, applies it to drafts and publishes it." +// proposedNote follows the result of a proposal: where it went, that nothing changed yet, and what the +// human's apply does, by the change class of what it proposes (metaversion.ClassOf, issue #22): an edit +// of a draft type goes to drafts once the project is delivered; a NEW document of a NewHidden type (a +// table, a field, an N-N relation) is created at apply but the customer sees it only after a publish; +// anything else (access, approvals, work queues, records) takes effect when applied. The most immediate +// effect among the cards wins, and a card with no envelope counts as immediate (fail-safe). +func proposedNote(added []ai.DraftItem) string { + const saved = "Saved as a card in the builder's Studio thread. Nothing has changed: a human reviews the card and applies it" + now, hidden := false, false + for _, it := range added { + c := metaversion.ClassOf("") + if it.Change != nil { + c = metaversion.ClassOf(it.Change.DocType) + } + switch { + case c.NewHidden && it.Change.Op != "update" && it.Change.Op != "delete": // a card that edits nothing is new + hidden = true + case c.Kind != metaversion.Draft: + now = true + } + } + switch { + case now: + return saved + ", and it takes effect as soon as it is applied: there is no draft or publish step for it." + case hidden: + return saved + ", which creates it; once the project is delivered the customer sees it only after it is published." + } + return saved + "; once the project is delivered it goes to drafts and reaches users when it is published." +} // call runs one tool as the token's builder. A propose_* call first reads the thread's earlier // proposals still pending (so it may build on them, as within one chat turn), and a proposal that @@ -174,6 +201,11 @@ func (s *server) call(ctx context.Context, req *mcp.CallToolRequest) (res *mcp.C return out, nil } draft, err := json.Marshal(added) + if err == nil && len(draft) > maxProposalBytes { + return &mcp.CallToolResult{IsError: true, Content: []mcp.Content{&mcp.TextContent{Text: fmt.Sprintf( + "PROPOSAL_TOO_LARGE: this proposal is %d KiB, more than the %d KiB one Studio card holds, so nothing was proposed. Split it into smaller proposals.", + len(draft)>>10, maxProposalBytes>>10)}}}, nil + } if err == nil { _, err = s.threads.AppendTurn(ctx, p.TenantID, p.UserID, p.SessionID, "", "[MCP] Agent gọi "+req.Params.Name, "Agent đề xuất qua MCP: "+result(answer).Result.Buffered+".", draft) @@ -181,7 +213,7 @@ func (s *server) call(ctx context.Context, req *mcp.CallToolRequest) (res *mcp.C if err != nil { return s.threadError(p, err), nil } - out.Content = append(out.Content, &mcp.TextContent{Text: proposedNote}) + out.Content = append(out.Content, &mcp.TextContent{Text: proposedNote(added)}) return out, nil } @@ -199,23 +231,41 @@ func (s *server) frozen(ctx context.Context, p services.MCPPrincipal) (time.Time return until, frozen } +// Issue #22: a key holder could append to its thread without end, and every proposal re-reads the +// whole thread. maxThreadTurns caps the turns one thread takes (the opening turn included); a key that +// needs more is replaced by a new one, which opens a new thread. maxProposalBytes caps one turn's +// draft row; the SDK's own 4 MiB request cap was the only bound before. +const ( + maxThreadTurns = 200 + maxProposalBytes = 256 << 10 +) + +// errThreadFull is a thread at maxThreadTurns. +var errThreadFull = errors.New("mcpserver: thread full") + // priorProposals reads the proposals of the token's thread that are still pending: a card the builder // applied, discarded or undid in the Studio is not replayed (issue #42), so the validators judge it -// by the live schema and the builder's drafts only. +// by the live schema and the builder's drafts only. A full thread is errThreadFull. func (s *server) priorProposals(ctx context.Context, p services.MCPPrincipal) ([]ai.DraftItem, error) { _, msgs, err := s.threads.GetSession(ctx, p.TenantID, p.UserID, p.SessionID) if err != nil { return nil, fmt.Errorf("mcpserver.priorProposals: %w", err) } + if len(msgs) >= 2*maxThreadTurns { // a turn is two messages: the call and the proposal + return nil, errThreadFull + } return ai.PendingProposals(msgs), nil } // threadError is the tool error of a proposal that cannot reach its thread. func (s *server) threadError(p services.MCPPrincipal, err error) *mcp.CallToolResult { msg := "THREAD_UNAVAILABLE: the proposal could not be saved to the Studio thread, so nothing was proposed. Try again." - if errors.Is(err, ai.ErrSessionNotFound) { + switch { + case errors.Is(err, errThreadFull): + msg = fmt.Sprintf("THREAD_FULL: the Studio thread of this token holds %d turns, the most one thread takes, so nothing was proposed. Ask the builder to issue a new MCP token: it opens a new thread.", maxThreadTurns) + case errors.Is(err, ai.ErrSessionNotFound): msg = "THREAD_DELETED: the builder deleted the Studio thread of this token, so nothing was proposed. Ask them to issue a new MCP token." - } else { + default: s.logger.Error("mcpserver: token thread unavailable", zap.String("tenant_id", p.TenantID), zap.String("mcp_token_id", p.TokenID), zap.Error(err)) } return &mcp.CallToolResult{Content: []mcp.Content{&mcp.TextContent{Text: msg}}, IsError: true} diff --git a/nexus-platform/internal/mcpserver/mcpserver_test.go b/nexus-platform/internal/mcpserver/mcpserver_test.go index 1bc1883..09bcfe6 100644 --- a/nexus-platform/internal/mcpserver/mcpserver_test.go +++ b/nexus-platform/internal/mcpserver/mcpserver_test.go @@ -409,3 +409,85 @@ func TestCall_DuringAFreezeReadsWorkProposalsDoNot(t *testing.T) { t.Fatalf("a read while frozen: %s (error %v); want it served", text(res), res.IsError) } } + +// Issue #22: a key holder could grow its thread without end, and every proposal re-reads the whole +// thread. A thread at its turn cap takes no more proposals (reads still work), with a code that says +// what to do; one turn below it, a proposal lands. +func TestCall_AFullThreadTakesNoMoreProposals(t *testing.T) { + th := &fakeThreads{msgs: make([]ai.Message, 2*maxThreadTurns)} + run := &fakeRunner{res: `{"ok":true,"result":{"buffered":"entity \"x\""}}`, added: []ai.DraftItem{{Kind: "entity", Entity: &ai.DraftEntity{Name: "x"}}}} + ts := serve(t, &fakeVerifier{}, run, th) + + res := callTool(t, ts, "nexus_propose_entity", map[string]any{"name": "x"}) + if !res.IsError || !strings.HasPrefix(text(res), "THREAD_FULL:") || len(run.calls)+len(th.appends) != 0 { + t.Fatalf("propose on a full thread: %s (error %v), ran %d, wrote %d; want THREAD_FULL before any work", text(res), res.IsError, len(run.calls), len(th.appends)) + } + th.msgs = th.msgs[:2*maxThreadTurns-2] + if res = callTool(t, ts, "nexus_propose_entity", map[string]any{"name": "x"}); res.IsError || len(th.appends) != 1 { + t.Fatalf("one turn below the cap: %s (error %v); want the proposal to land", text(res), res.IsError) + } +} + +// One proposal's thread row is capped: an oversized one is refused and nothing is written. +func TestCall_AnOversizedProposalIsRefused(t *testing.T) { + big := []ai.DraftItem{{Kind: "records", Records: &ai.DraftRecords{Entity: "suppliers", Rows: []map[string]any{{"note": strings.Repeat("x", maxProposalBytes)}}}}} + run := &fakeRunner{res: `{"ok":true,"result":{"buffered":"1 record mẫu cho \"suppliers\""}}`, added: big} + th := &fakeThreads{} + res := callTool(t, serve(t, &fakeVerifier{}, run, th), "nexus_propose_records", map[string]any{"entity": "suppliers"}) + if !res.IsError || !strings.HasPrefix(text(res), "PROPOSAL_TOO_LARGE:") || len(th.appends) != 0 { + t.Fatalf("an oversized proposal: %s (error %v), wrote %d; want PROPOSAL_TOO_LARGE and no write", text(res), res.IsError, len(th.appends)) + } +} + +// Issue #22: what the agent is told after a proposal follows the change class of that card, per kind of +// envelope the builder tools write (internal/ai/change.go): access and the other direct types apply at once; +// a NEW table, field or N-N relation is created at apply but hidden from the customer until a publish; an +// edit of a draft type goes to drafts. No tool description promises a draft and a publish for every card. +func TestProposedNote_FollowsTheChangeClassPerKind(t *testing.T) { + const now, hidden, drafts = "takes effect as soon as it is applied", "sees it only after it is published", "goes to drafts" + for _, tc := range []struct{ kind, docType, op, want string }{ + {"access", "role", "update", now}, + {"records", "records", "create", now}, + {"approval", "approval", "create", now}, + {"workqueue", "workqueue", "create", now}, + {"relationship", "relationship", "create", hidden}, + {"entity", "entity", "create", hidden}, + {"field", "field", "create", hidden}, + {"edit_field", "field", "update", drafts}, + {"delete_field", "field", "delete", drafts}, + {"delete_entity", "entity", "delete", drafts}, + {"layout", "layout", "update", drafts}, + {"workflow", "workflow", "create", drafts}, + {"report", "report", "create", drafts}, + {"dashboard", "dashboard", "create", drafts}, + {"app", "app", "create", drafts}, + {"no envelope", "", "", now}, + } { + item := ai.DraftItem{Kind: tc.kind} + if tc.docType != "" { + item.Change = &ai.DraftChange{DocType: tc.docType, Op: tc.op} + } + got := proposedNote([]ai.DraftItem{item}) + for _, phrase := range []string{now, hidden, drafts} { + if strings.Contains(got, phrase) != (phrase == tc.want) { + t.Errorf("%s (%s %s): %q; want only %q", tc.kind, tc.docType, tc.op, got, tc.want) + break + } + } + } + if got := proposedNote([]ai.DraftItem{{Change: &ai.DraftChange{DocType: "field", Op: "update"}}, {Change: &ai.DraftChange{DocType: "role", Op: "update"}}}); !strings.Contains(got, now) { + t.Errorf("a field edit with an access card: %q; want the immediate effect named", got) + } +} + +func TestCall_TheNoteFollowsTheChangeClass(t *testing.T) { + run := &fakeRunner{res: `{"ok":true,"result":{"buffered":"x"}}`, added: []ai.DraftItem{{Kind: "access", Change: &ai.DraftChange{DocType: "role", Op: "update"}}}} + if got := text(callTool(t, serve(t, &fakeVerifier{}, run, &fakeThreads{}), "nexus_propose_access", nil)); !strings.Contains(got, "no draft or publish step") { + t.Errorf("nexus_propose_access result: %q; want the access card's own effect", got) + } + for _, tl := range tools(ai.ToolDefinitions()) { + if strings.Contains(tl.Description, "publishes it") { + t.Errorf("%s promises a draft and a publish for its card: %q", tl.Name, tl.Description[strings.LastIndex(tl.Description, "MCP:"):]) + } + } +} diff --git a/nexus-platform/internal/mcpserver/tools.go b/nexus-platform/internal/mcpserver/tools.go index e8f0996..31884b2 100644 --- a/nexus-platform/internal/mcpserver/tools.go +++ b/nexus-platform/internal/mcpserver/tools.go @@ -31,8 +31,9 @@ func isRead(name string) bool { // a card) and none reaches outside the workspace. Shared and never written. var no = false -// proposeNote ends every propose tool's description: what the outside agent must tell its user. -const proposeNote = " MCP: the proposal is saved as a card in the builder's Studio thread; nothing changes until a human applies it to drafts and publishes it." +// proposeNote ends every propose tool's description: what the outside agent must tell its user. It holds +// for every change class; the result of a call says what applying that card does (proposedNote). +const proposeNote = " MCP: the proposal is saved as a card in the builder's Studio thread; nothing changes until a human reviews and applies it." // tools turns the builder agent's tool definitions (ai.ToolDefinitions) into MCP tools: every read // tool and every propose_* tool, renamed nexus_, with the same description and JSON schema, diff --git a/nexus-platform/internal/middleware/mcp_ratelimit.go b/nexus-platform/internal/middleware/mcp_ratelimit.go new file mode 100644 index 0000000..7b2f893 --- /dev/null +++ b/nexus-platform/internal/middleware/mcp_ratelimit.go @@ -0,0 +1,98 @@ +// Package middleware — mcp_ratelimit.go: the request brakes in front of /mcp (issue #22). /mcp sits +// outside /api/v1, so none of the API's limiters covered it: every unauthenticated nxm_ guess cost one +// indexed SELECT with nothing slowing it, and a key holder had no request budget at all. +// +// Two brakes, both the API's own sliding window (memRateLimiter), and every request is charged to +// exactly ONE of them: +// - a token not yet seen working (a guess, or a real key's first request) spends its client IP's +// budget of lookups — the same per-minute budget the API-key brake gives an IP (queue #356); +// - a token seen working spends its own budget — the per-key budget of the data plane (#52) — so +// the real agents behind one NAT address never wait on a prober's spent IP budget. +// +// A token is "seen working" once /mcp answered it with a 2xx; a 401 forgets it, so a revoked or +// expired key goes back to its IP's budget. A request without an nxm_ bearer passes: the handler +// refuses it without a lookup. Refusals are the canonical RATE_LIMITED 429 (writeRateLimited429). +// +// Ceiling: in-memory, per process, like every limiter here (RM-15 note); a shared store is the upgrade. +package middleware + +import ( + "net" + "net/http" + "strings" + "sync" + "time" + + "github.com/gin-gonic/gin" + + "nexus/platform/internal/auth" +) + +// mcpTokenPrefix is services.MCPTokenPrefix; this package does not import services. +const mcpTokenPrefix = "nxm_" + +// mcpWorkingMax caps the memory of working tokens (~100 bytes an entry). +const mcpWorkingMax = 10000 + +// MCPRateLimitConfig holds the /mcp brakes. A budget <= 0 switches that brake off. +type MCPRateLimitConfig struct { + // ProbeMax is how many lookups of not-yet-working tokens one client IP may make per Window. + ProbeMax int + // KeyMax is how many requests one working token may make per Window. + KeyMax int + // Window is the sliding-window span of both budgets. + Window time.Duration + // TrustedProxyCIDRs: see RateLimitConfig.TrustedProxyCIDRs (clientIP). + TrustedProxyCIDRs []*net.IPNet +} + +// MCPRateLimit returns the gin middleware to mount in front of the /mcp handler. +func MCPRateLimit(cfg MCPRateLimitConfig) gin.HandlerFunc { + if cfg.Window <= 0 || (cfg.ProbeMax <= 0 && cfg.KeyMax <= 0) { + return func(c *gin.Context) { c.Next() } + } + var probes, keys *memRateLimiter + if cfg.ProbeMax > 0 { + probes = newMemRateLimiter(cfg.ProbeMax, cfg.Window) + } + if cfg.KeyMax > 0 { + keys = newMemRateLimiter(cfg.KeyMax, cfg.Window) + } + var mu sync.Mutex + working := map[string]struct{}{} // token hash → seen answered 2xx + + return func(c *gin.Context) { + tok, _ := extractBearer(c.GetHeader("Authorization")) + if !strings.HasPrefix(tok, mcpTokenPrefix) { + c.Next() + return + } + hash := auth.HashRefreshToken(tok) // the SHA-256 sys_mcp_tokens stores; never the raw token + mu.Lock() + _, known := working[hash] + mu.Unlock() + lim, bucket := probes, "mcpip:"+clientIP(c.Request, cfg.TrustedProxyCIDRs) + if known { + lim, bucket = keys, "mcpkey:"+hash + } + if lim != nil && !lim.allow(bucket) { + writeRateLimited429(c, cfg.Window) + return + } + c.Next() + status := c.Writer.Status() + mu.Lock() + defer mu.Unlock() + switch { + case status == http.StatusUnauthorized: + delete(working, hash) + case status < 300 && !known: + // ponytail: wholesale reset when full, like APIKeyService.markDead; only more than + // mcpWorkingMax live tokens in one process fill it, and each is back on its next 2xx. + if len(working) >= mcpWorkingMax { + working = map[string]struct{}{} + } + working[hash] = struct{}{} + } + } +} diff --git a/nexus-platform/internal/middleware/mcp_ratelimit_test.go b/nexus-platform/internal/middleware/mcp_ratelimit_test.go new file mode 100644 index 0000000..4ca6adf --- /dev/null +++ b/nexus-platform/internal/middleware/mcp_ratelimit_test.go @@ -0,0 +1,152 @@ +package middleware + +import ( + "net" + "net/http" + "net/http/httptest" + "strings" + "testing" + "time" + + "github.com/gin-gonic/gin" +) + +// Issue #22 item 2: /mcp had no brake. The handler below stands in for mcpserver: it "looks up" the +// token (lookups counts what would be a SELECT) and answers 200 for a live key, 401 otherwise. +type mcpFake struct { + live map[string]bool + lookups int +} + +func (f *mcpFake) router(cfg MCPRateLimitConfig) *gin.Engine { + gin.SetMode(gin.TestMode) + r := gin.New() + r.Any("/mcp", MCPRateLimit(cfg), func(c *gin.Context) { + tok, _ := extractBearer(c.GetHeader("Authorization")) + if !strings.HasPrefix(tok, "nxm_") { + c.Status(http.StatusUnauthorized) // refused without a lookup, as mcpserver does + return + } + f.lookups++ + if f.live[tok] { + c.Status(http.StatusOK) + return + } + c.Status(http.StatusUnauthorized) + }) + return r +} + +func mcpCall(r *gin.Engine, ip, token string) *httptest.ResponseRecorder { + req := httptest.NewRequest(http.MethodPost, "/mcp", strings.NewReader(`{}`)) + req.RemoteAddr = ip + ":5000" + if token != "" { + req.Header.Set("Authorization", "Bearer "+token) + } + w := httptest.NewRecorder() + r.ServeHTTP(w, req) + return w +} + +func TestMCPRateLimit_GuessesSpendTheIPsBudgetAndAWorkingKeyKeepsWorking(t *testing.T) { + f := &mcpFake{live: map[string]bool{"nxm_live": true}} + r := f.router(MCPRateLimitConfig{ProbeMax: 3, KeyMax: 100, Window: time.Minute}) + const office, elsewhere = "203.0.113.7", "198.51.100.2" + + if w := mcpCall(r, office, "nxm_live"); w.Code != http.StatusOK { // first use: charged to the IP (1 of 3) + t.Fatalf("a live key's first call: %d", w.Code) + } + for i, want := range []int{401, 401, 429, 429} { // the prober spends the other 2, then is refused + if w := mcpCall(r, office, "nxm_guess"+string(rune('a'+i))); w.Code != want { + t.Fatalf("guess %d: %d; want %d", i+1, w.Code, want) + } + } + if f.lookups != 3 { + t.Fatalf("lookups = %d; want 3 (a refused guess costs no lookup)", f.lookups) + } + w := mcpCall(r, office, "nxm_guessz") + if w.Header().Get("Retry-After") == "" || !strings.Contains(w.Body.String(), `"code":"RATE_LIMITED"`) { + t.Fatalf("refusal = %v %s; want Retry-After and the canonical RATE_LIMITED body", w.Header(), w.Body.String()) + } + // The working key behind the same address is not the prober: it spends its own budget. + if w := mcpCall(r, office, "nxm_live"); w.Code != http.StatusOK { + t.Fatalf("the working key after the IP's budget was spent: %d; want 200", w.Code) + } + // Another address has its own budget. + if w := mcpCall(r, elsewhere, "nxm_guess"); w.Code != http.StatusUnauthorized { + t.Fatalf("a guess from another address: %d; want 401", w.Code) + } + // No nxm_ bearer is never braked: the handler refuses it without a lookup. + for range 5 { + if w := mcpCall(r, office, ""); w.Code != http.StatusUnauthorized { + t.Fatalf("no credential: %d; want 401", w.Code) + } + } +} + +func TestMCPRateLimit_AWorkingKeyHasItsOwnBudget(t *testing.T) { + f := &mcpFake{live: map[string]bool{"nxm_live": true, "nxm_other": true}} + r := f.router(MCPRateLimitConfig{ProbeMax: 100, KeyMax: 2, Window: time.Minute}) + const ip = "203.0.113.7" + for i, want := range []int{200, 200, 200, 429} { // first call on the IP, then 2 on the key + if w := mcpCall(r, ip, "nxm_live"); w.Code != want { + t.Fatalf("call %d: %d; want %d", i+1, w.Code, want) + } + } + if w := mcpCall(r, ip, "nxm_other"); w.Code != http.StatusOK { + t.Fatalf("another key: %d; want 200 (budgets are per key)", w.Code) + } +} + +func TestMCPRateLimit_ARevokedKeyGoesBackToTheIPsBudget(t *testing.T) { + f := &mcpFake{live: map[string]bool{"nxm_live": true}} + r := f.router(MCPRateLimitConfig{ProbeMax: 2, KeyMax: 100, Window: time.Minute}) + const ip = "203.0.113.7" + mcpCall(r, ip, "nxm_live") // IP budget 1 of 2 + f.live["nxm_live"] = false // revoked + for i, want := range []int{401, 401, 429} { // known: key budget; then forgotten: the IP's last lookup; then braked + if w := mcpCall(r, ip, "nxm_live"); w.Code != want { + t.Fatalf("call %d after revoke: %d; want %d", i+1, w.Code, want) + } + } +} + +func TestMCPRateLimit_OffWhenBudgetsAreZero(t *testing.T) { + f := &mcpFake{} + r := f.router(MCPRateLimitConfig{Window: time.Minute}) + for range 10 { + if w := mcpCall(r, "203.0.113.7", "nxm_guess"); w.Code != http.StatusUnauthorized { + t.Fatalf("no budget configured: %d; want 401 (no brake)", w.Code) + } + } +} + +// Behind Caddy every request comes from Caddy's address. Without TRUSTED_PROXY_CIDRS one prober spends every +// client's lookup budget; with the compose network trusted (docker-compose.yml), each client has its own. +func TestMCPRateLimit_BehindTheProxyEachClientHasItsOwnBudget(t *testing.T) { + _, compose, _ := net.ParseCIDR("10.213.47.0/24") + viaCaddy := func(r *gin.Engine, client string) int { + req := httptest.NewRequest(http.MethodPost, "/mcp", strings.NewReader(`{}`)) + req.RemoteAddr = "10.213.47.2:5000" // Caddy on the compose network + req.Header.Set("X-Forwarded-For", client) + req.Header.Set("Authorization", "Bearer nxm_guess") + w := httptest.NewRecorder() + r.ServeHTTP(w, req) + return w.Code + } + for _, tc := range []struct { + name string + trusted []*net.IPNet + want int + }{ + {"proxy not trusted: one bucket for everyone", nil, http.StatusTooManyRequests}, + {"compose network trusted: a bucket per client", []*net.IPNet{compose}, http.StatusUnauthorized}, + } { + r := (&mcpFake{}).router(MCPRateLimitConfig{ProbeMax: 2, KeyMax: 100, Window: time.Minute, TrustedProxyCIDRs: tc.trusted}) + viaCaddy(r, "198.51.100.1") + viaCaddy(r, "198.51.100.1") // the prober spends its 2 + if got := viaCaddy(r, "203.0.113.50"); got != tc.want { + t.Errorf("%s: another client's guess = %d; want %d", tc.name, got, tc.want) + } + } +} diff --git a/nexus-web/app/api/v1/[...path]/route.ts b/nexus-web/app/api/v1/[...path]/route.ts index 6e11c0a..0675f6a 100644 --- a/nexus-web/app/api/v1/[...path]/route.ts +++ b/nexus-web/app/api/v1/[...path]/route.ts @@ -1,83 +1,17 @@ import type { NextRequest } from "next/server"; +import { devProxy } from "@/lib/devProxy"; -// DEV-ONLY API proxy (Layout Engine L2 — browser E2E). -// -// The Go backend (:8090) is CORS fail-closed: it only accepts same-origin / no-Origin requests, so -// a browser on the Next dev port (localhost:3000) is rejected with 403 on EVERY call (login + GETs). -// A plain next.config rewrite doesn't help because it forwards the browser's Origin header verbatim. -// -// This Route Handler runs on the Next SERVER and re-issues the request to the backend with NO Origin -// header (server-to-server fetch), so the browser stays same-origin (/api/v1/*) and the backend sees -// a same-origin/no-Origin call → 200. Guarded by NODE_ENV so it is inert in the standalone prod build -// (prod sets NEXT_PUBLIC_API_BASE to the real backend URL and never hits this handler). -// -// Scope: dev verification only. Not a production proxy. - -const TARGET = process.env.DEV_API_PROXY_TARGET || "http://localhost:8090"; - -// Headers we must NOT forward to the backend (hop-by-hop or origin/host that would re-trigger CORS). -const STRIP = new Set([ - "host", - "origin", - "referer", - "connection", - "content-length", - "accept-encoding", -]); - -async function proxy(req: NextRequest, path: string[]) { - if (process.env.NODE_ENV !== "development") { - return new Response("Not found", { status: 404 }); - } - - const search = req.nextUrl.search; // preserve ?expand=/?sort=/?page= etc. - const url = `${TARGET}/api/v1/${path.join("/")}${search}`; - - const headers = new Headers(); - req.headers.forEach((value, key) => { - if (!STRIP.has(key.toLowerCase())) headers.set(key, value); - }); - - const hasBody = req.method !== "GET" && req.method !== "HEAD"; - const body = hasBody ? await req.arrayBuffer() : undefined; - - const upstream = await fetch(url, { - method: req.method, - headers, - body, - redirect: "manual", - }); - - // Mirror the upstream response (status + body + content-type) back to the browser, same-origin. - const resHeaders = new Headers(); - const ct = upstream.headers.get("content-type"); - if (ct) resHeaders.set("content-type", ct); - return new Response(upstream.body, { - status: upstream.status, - statusText: upstream.statusText, - headers: resHeaders, - }); -} +// DEV-ONLY API proxy to DEV_API_PROXY_TARGET: lib/devProxy.ts says why and when it answers. type Ctx = { params: Promise<{ path: string[] }> }; -export async function GET(req: NextRequest, { params }: Ctx) { +async function proxy(req: NextRequest, { params }: Ctx) { const { path } = await params; - return proxy(req, path); -} -export async function POST(req: NextRequest, { params }: Ctx) { - const { path } = await params; - return proxy(req, path); -} -export async function PUT(req: NextRequest, { params }: Ctx) { - const { path } = await params; - return proxy(req, path); -} -export async function PATCH(req: NextRequest, { params }: Ctx) { - const { path } = await params; - return proxy(req, path); -} -export async function DELETE(req: NextRequest, { params }: Ctx) { - const { path } = await params; - return proxy(req, path); + return devProxy(req, `/api/v1/${path.join("/")}`); } + +export const GET = proxy; +export const POST = proxy; +export const PUT = proxy; +export const PATCH = proxy; +export const DELETE = proxy; diff --git a/nexus-web/app/mcp/route.ts b/nexus-web/app/mcp/route.ts new file mode 100644 index 0000000..f3e1f78 --- /dev/null +++ b/nexus-web/app/mcp/route.ts @@ -0,0 +1,11 @@ +import type { NextRequest } from "next/server"; +import { devProxy } from "@/lib/devProxy"; + +// DEV-ONLY: `next dev` serves the endpoint the Studio prints for an agent (lib/admin.ts mcpEndpoint), so a +// contributor's `claude mcp add` line connects (issue #22). lib/devProxy.ts says why and when it answers. + +const proxy = (req: NextRequest) => devProxy(req, "/mcp"); + +export const GET = proxy; +export const POST = proxy; +export const DELETE = proxy; diff --git a/nexus-web/components/screens/admin/McpConnect.test.tsx b/nexus-web/components/screens/admin/McpConnect.test.tsx index 3156304..6ec4138 100644 --- a/nexus-web/components/screens/admin/McpConnect.test.tsx +++ b/nexus-web/components/screens/admin/McpConnect.test.tsx @@ -118,7 +118,7 @@ describe("McpConnect", () => { global.fetch = routedFetch([LIVE]) as unknown as typeof fetch; mount(); fireEvent.click(await screen.findByRole("button", { name: "Mở cuộc trò chuyện của khoá nxm_AbCdEfGhIjKl…" })); - await waitFor(() => expect(openThread).toHaveBeenCalledWith("sess-1")); + await waitFor(() => expect(openThread).toHaveBeenCalledWith("sess-1", LIVE.expiresAt)); // the key's expiry: the thread follows it until then }); it("a deleted conversation says to revoke the key and make a new one", async () => { diff --git a/nexus-web/components/screens/admin/McpConnect.tsx b/nexus-web/components/screens/admin/McpConnect.tsx index f9f58c9..01c33a4 100644 --- a/nexus-web/components/screens/admin/McpConnect.tsx +++ b/nexus-web/components/screens/admin/McpConnect.tsx @@ -111,7 +111,7 @@ function McpConnectSection({ slug }: { slug: string }) { {openThread && ( )} diff --git a/nexus-web/components/studio/assistant/AssistantPanel.thread.test.tsx b/nexus-web/components/studio/assistant/AssistantPanel.thread.test.tsx index e9bb11a..408f96c 100644 --- a/nexus-web/components/studio/assistant/AssistantPanel.thread.test.tsx +++ b/nexus-web/components/studio/assistant/AssistantPanel.thread.test.tsx @@ -3,7 +3,7 @@ // are the REAL ones; the session read and the identity seams are mocked. import { QueryClient, QueryClientProvider } from "@tanstack/react-query"; import { act, fireEvent, render, screen, waitFor } from "@testing-library/react"; -import { beforeEach, describe, expect, it, vi } from "vitest"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; vi.mock("next/navigation", () => ({ useSearchParams: () => new URLSearchParams("") })); vi.mock("@/lib/studioContext", () => ({ @@ -16,6 +16,10 @@ vi.mock("@/lib/studioContext", () => ({ vi.mock("@/lib/previewSession", () => ({ getPreviewToken: () => null })); const pub = { q: {} as Record }; vi.mock("../usePublishState", () => ({ usePublishState: () => pub.q })); +// A turn the builder sends stays in flight: what matters here is what the thread shows meanwhile. +vi.mock("@/lib/aiBuilderStream", async (importOriginal) => ({ + ...(await importOriginal()), aiBuilderChatStream: vi.fn(() => new Promise(() => {})), +})); vi.mock("@/lib/api", async (importOriginal) => { const actual = await importOriginal(); return { @@ -29,7 +33,7 @@ import { addField, createWorkflow, discardDraft, getAiSession, listDraftChanges, import { resetAssistantOpenForTests, useAssistantOpen } from "@/lib/assistantOpen"; import { parseStudioPath } from "@/lib/studioRoutes"; import { AssistantMount } from "./AssistantMount"; -import { AssistantProvider, useOpenThread } from "./AssistantProvider"; +import { AssistantProvider, useAssistant, useOpenThread } from "./AssistantProvider"; const THREAD = { id: "sess-1", @@ -47,12 +51,19 @@ const THREAD = { ], }; +/** The expiry of the agent key bound to the thread, as McpConnect passes it. */ +const liveUntil = { at: "2999-01-01T00:00:00Z" }; + function Opener() { const open = useOpenThread(); const shown = useAssistantOpen(); + const { send } = useAssistant(); return ( <> + + + {String(shown)} ); @@ -141,3 +152,112 @@ describe("opening a saved conversation", () => { expect(screen.getByRole("button", { name: "mo" })).toBeDisabled(); }); }); + +// Issue #22: while the agent key bound to the thread is live, the open thread shows what the agent adds without a reopen: +// it re-reads itself every 5 s while visible, stops after 10 minutes with nothing new, and a focus wakes it again. +describe("an open thread an agent key is bound to", () => { + const LATER = { + ...THREAD, + messages: [ + ...THREAD.messages, + { seq: 4, role: "user", content: "[MCP] Agent gọi nexus_propose_entity", draft: null, createdAt: "2026-10-17T03:06:00Z" }, + { seq: 5, role: "assistant", content: "Agent đề xuất qua MCP: entity \"kho\".", createdAt: "2026-10-17T03:06:00Z", + draft: [{ kind: "entity", entity: { name: "kho", label: "Kho", fields: [] } }] }, + ], + }; + const tick = (ms: number) => act(async () => { await vi.advanceTimersByTimeAsync(ms); }); + const openWith = async (name: string) => { await act(async () => { fireEvent.click(screen.getByRole("button", { name })); }); }; + + beforeEach(() => { vi.useFakeTimers(); liveUntil.at = "2999-01-01T00:00:00Z"; }); + afterEach(() => { vi.useRealTimers(); }); + + it("shows the agent's new card without a reopen, and keeps what was applied", async () => { + mount(); + await openWith("mo-key"); + fireEvent.click(screen.getByRole("button", { name: "Áp dụng" })); + await tick(0); + expect(addField).toHaveBeenCalledTimes(1); + vi.mocked(getAiSession).mockResolvedValue(LATER as never); + await tick(5_000); + expect(screen.getByText("[MCP] Agent gọi nexus_propose_entity")).toBeInTheDocument(); + // the field card applied before the re-read is still applied: one Áp dụng left, the new table's + expect(screen.getAllByRole("button", { name: "Áp dụng" })).toHaveLength(1); + }); + + it("stops reading after ten quiet minutes; a focus reads again", async () => { + mount(); + await openWith("mo-key"); + await tick(10 * 60_000 + 5_000); + const reads = vi.mocked(getAiSession).mock.calls.length; + await tick(60_000); + expect(getAiSession).toHaveBeenCalledTimes(reads); + vi.mocked(getAiSession).mockResolvedValue(LATER as never); + await act(async () => { window.dispatchEvent(new Event("focus")); }); + await tick(0); + expect(screen.getByText("[MCP] Agent gọi nexus_propose_entity")).toBeInTheDocument(); + }); + + // The three guards of a re-read, and the race between a read in flight and the builder's own turn. + const deferred = () => { let release!: (v: unknown) => void; const p = new Promise((r) => { release = r; }); return { p, release }; }; + const TWO = { ...THREAD, id: "sess-2", messages: [{ seq: 0, role: "user", content: "Cuộc khác", draft: null, createdAt: "2026-10-17T03:00:00Z" }] }; + + it("a read in flight when the builder sends a message never replaces that message", async () => { + mount(); + await openWith("mo-key"); + const read = deferred(); + vi.mocked(getAiSession).mockImplementation(() => read.p as never); + await tick(5_000); // the poll's read is out + expect(getAiSession).toHaveBeenCalledTimes(2); + await act(async () => { fireEvent.click(screen.getByRole("button", { name: "gui" })); }); + await act(async () => { read.release(LATER); }); + expect(screen.getByText("Thêm cột kho")).toBeInTheDocument(); + expect(screen.queryByText("[MCP] Agent gọi nexus_propose_entity")).toBeNull(); + }); + + it("a turn of the builder's own stops the re-read", async () => { + mount(); + await openWith("mo-key"); + await act(async () => { fireEvent.click(screen.getByRole("button", { name: "gui" })); }); + await tick(30_000); + expect(getAiSession).toHaveBeenCalledTimes(1); + }); + + it("a hidden tab does not read; showing it again does", async () => { + mount(); + await openWith("mo-key"); + const hidden = vi.spyOn(document, "hidden", "get").mockReturnValue(true); + await tick(30_000); + expect(getAiSession).toHaveBeenCalledTimes(1); + hidden.mockReturnValue(false); + vi.mocked(getAiSession).mockResolvedValue(LATER as never); + await act(async () => { document.dispatchEvent(new Event("visibilitychange")); }); + await tick(0); + expect(getAiSession).toHaveBeenCalledTimes(2); + expect(screen.getByText("[MCP] Agent gọi nexus_propose_entity")).toBeInTheDocument(); + hidden.mockRestore(); + }); + + it("a late read of a thread never lands in another thread opened meanwhile", async () => { + mount(); + await openWith("mo-key"); + const read = deferred(); + vi.mocked(getAiSession).mockImplementation(((id: string) => (id === "sess-2" ? Promise.resolve(TWO) : read.p)) as never); + await tick(5_000); // sess-1's read is out + await openWith("mo-2"); + expect(screen.getByText("Cuộc khác")).toBeInTheDocument(); + await act(async () => { read.release(LATER); }); + expect(screen.getByText("Cuộc khác")).toBeInTheDocument(); + expect(screen.queryByText("[MCP] Agent gọi nexus_propose_entity")).toBeNull(); + }); + + it("is not followed without a live key: no key, or an expired one", async () => { + mount(); + await openWith("mo"); + await tick(60_000); + expect(getAiSession).toHaveBeenCalledTimes(1); + liveUntil.at = "2000-01-01T00:00:00Z"; + await openWith("mo-key"); + await tick(60_000); + expect(getAiSession).toHaveBeenCalledTimes(2); + }); +}); diff --git a/nexus-web/components/studio/assistant/AssistantProvider.tsx b/nexus-web/components/studio/assistant/AssistantProvider.tsx index 6f97a34..c5eb2ee 100644 --- a/nexus-web/components/studio/assistant/AssistantProvider.tsx +++ b/nexus-web/components/studio/assistant/AssistantProvider.tsx @@ -29,14 +29,21 @@ import type { StudioRoute } from "@/lib/studioRoutes"; import { usePublishState } from "../usePublishState"; import { useAssistantChat } from "./useAssistantChat"; +// How often an open MCP thread re-reads itself, and after how long without a new card it stops (issue #22). +const FOLLOW_POLL_MS = 5_000; +const FOLLOW_IDLE_MS = 10 * 60_000; +/** A turn this tab sent (a read-back turn is m_, serverMessagesToTurns). */ +const ownTurn = (x: ChatTurn) => !x.id.startsWith("m_"); + type Ask = (entity: string, recordId: string) => void; const AskCtx = createContext(null); /** null = no assistant on this page (outside the project frame, or the assistant is off) ⇒ callers must not draw the button. */ export const useAskAssistant = (): Ask | null => useContext(AskCtx); -type OpenThread = (sessionId: string) => Promise; +type OpenThread = (sessionId: string, liveUntil?: string) => Promise; const OpenCtx = createContext(null); -/** Opens a saved conversation in the panel (an MCP agent's thread: issue #3); null where no panel mounts. Rejects when it cannot be read. */ +/** Opens a saved conversation in the panel (an MCP agent's thread: issue #3); null where no panel mounts. Rejects when it cannot be read. + * liveUntil = the expiry of the agent key bound to the thread: until then the open thread follows what the agent adds (issue #22). */ export const useOpenThread = (): OpenThread | null => useContext(OpenCtx); export type Attention = "working" | "proposal" | null; @@ -137,7 +144,7 @@ export function AssistantProvider({ slug, projectName, route, params, panel, chi ); const onDropped = useCallback(() => setRec(null), []); const chat = useAssistantChat({ context, onContextDropped: onDropped, assertScope }); - const { turns, setTurns, sending, runTurn, reportApplyFailure, sessionId } = chat; + const { turns, setTurns, sending, runTurn, reportApplyFailure, sessionId, sessionIdRef } = chat; const ask = useCallback((entity, recordId) => { setRec({ entity, recordId }); @@ -220,15 +227,54 @@ export function AssistantProvider({ slug, projectName, route, params, panel, chi const newChat = useCallback(() => { chat.reset(); setApplyMap({}); }, [chat]); // A saved conversation as a resumed session: its turns and cards, and what this browser already applied of it. - const openThread = useCallback(async (id) => { + const [follow, setFollow] = useState<{ id: string; until: number } | null>(null); + const openThread = useCallback(async (id, liveUntil) => { const s = await getAiSession(id); chat.reset(); chat.setTurns(serverMessagesToTurns(s.messages)); chat.setActiveSession(s.id); setApplyMap(loadApplyState(slug, s.id)); + setFollow(liveUntil ? { id: s.id, until: Date.parse(liveUntil) } : null); setAssistantOpen(true); }, [chat, slug]); + // Issue #22: an MCP agent adds cards to the thread its key is bound to; the open thread re-reads itself while that + // key is live: on focus, and every FOLLOW_POLL_MS while the tab is visible until FOLLOW_IDLE_MS pass with nothing new + // (focus wakes it). Read-back turns keep their ids (m_), so a card's apply state survives the re-read. A turn of + // this tab's own stops it: its cards carry ids of this tab, which the server's copy would replace. That is judged + // again when the read lands, on the turns as they are then: the builder may have sent one while it was out. + const turnsRef = useRef(turns); + useEffect(() => { turnsRef.current = turns; }); + const followId = follow && follow.id === sessionId ? follow.id : null; + const followUntil = follow?.until ?? 0; + useEffect(() => { + if (!followId) return; + let alive = true; + let grew = Date.now(); + const read = async (woken: boolean) => { + const now = Date.now(); + if (now >= followUntil) { setFollow(null); return; } // the key expired: nothing more will land here + if (woken) grew = now; + if (document.hidden || now - grew > FOLLOW_IDLE_MS) return; + if (turnsRef.current.some(ownTurn)) return; + const s = await getAiSession(followId).catch(() => null); + if (!alive || !s || sessionIdRef.current !== followId || s.messages.length <= turnsRef.current.length) return; + const next = serverMessagesToTurns(s.messages); + setTurns((cur) => (cur.some(ownTurn) || next.length <= cur.length ? cur : next)); + grew = Date.now(); + }; + const poll = setInterval(() => void read(false), FOLLOW_POLL_MS); + const wake = () => void read(true); + window.addEventListener("focus", wake); + document.addEventListener("visibilitychange", wake); + return () => { + alive = false; + clearInterval(poll); + window.removeEventListener("focus", wake); + document.removeEventListener("visibilitychange", wake); + }; + }, [followId, followUntil, sessionIdRef, setTurns]); + // ── the dot on the header button while the panel is closed ── const open = useAssistantOpen(); const proposalTurns = turns.filter((x) => x.role === "assistant" && hasDrafts(x.draft)).length; diff --git a/nexus-web/lib/admin.ts b/nexus-web/lib/admin.ts index 0ea65e1..06c1986 100644 --- a/nexus-web/lib/admin.ts +++ b/nexus-web/lib/admin.ts @@ -509,7 +509,8 @@ export async function revokeMcpToken(id: string): Promise { await adminReq("DELETE", `/admin/mcp-tokens/${encodeURIComponent(id)}`); } -/** Where an agent connects: the API's origin + /mcp (the one-command demo serves both on one origin). */ +/** Where an agent connects: the API's origin + /mcp (the one-command demo serves both on one origin; on `next dev` with a relative + * API base it is the dev origin, and app/mcp proxies it to the API). */ export function mcpEndpoint(): string { return `${new URL(BASE, window.location.origin).origin}/mcp`; } diff --git a/nexus-web/lib/devProxy.ts b/nexus-web/lib/devProxy.ts new file mode 100644 index 0000000..e66ef2d --- /dev/null +++ b/nexus-web/lib/devProxy.ts @@ -0,0 +1,61 @@ +import type { NextRequest } from "next/server"; + +// DEV-ONLY proxy to the Go backend, behind app/api/v1/[...path] (Layout Engine L2 — browser E2E) and app/mcp (issue #22). +// +// The Go backend (:8090) is CORS fail-closed: it only accepts same-origin / no-Origin requests, so +// a browser on the Next dev port (localhost:3000) is rejected with 403 on EVERY call (login + GETs). +// A plain next.config rewrite doesn't help because it forwards the browser's Origin header verbatim. +// +// The Route Handlers run on the Next SERVER and re-issue the request to the backend with NO Origin +// header (server-to-server fetch), so the browser stays same-origin (/api/v1/*) and the backend sees +// a same-origin/no-Origin call → 200. /mcp rides the same proxy so the `claude mcp add` line the Studio +// prints on `next dev` (lib/admin.ts mcpEndpoint: the dev origin + /mcp) reaches the API. Guarded by +// NODE_ENV so it is inert in the standalone prod build (prod sets NEXT_PUBLIC_API_BASE to the real +// backend URL, and the demo's Caddy routes /api and /mcp to the API before Next). +// +// Scope: dev verification only. Not a production proxy. + +// Headers we must NOT forward to the backend (hop-by-hop or origin/host that would re-trigger CORS). +const STRIP = new Set([ + "host", + "origin", + "referer", + "connection", + "content-length", + "accept-encoding", +]); + +/** Re-issues `req` to the backend at `path` (its query string kept); 404 outside `next dev`. */ +export async function devProxy(req: NextRequest, path: string): Promise { + if (process.env.NODE_ENV !== "development") { + return new Response("Not found", { status: 404 }); + } + + const target = process.env.DEV_API_PROXY_TARGET || "http://localhost:8090"; + const url = `${target}${path}${req.nextUrl.search}`; // preserve ?expand=/?sort=/?page= etc. + + const headers = new Headers(); + req.headers.forEach((value, key) => { + if (!STRIP.has(key.toLowerCase())) headers.set(key, value); + }); + + const hasBody = req.method !== "GET" && req.method !== "HEAD"; + const body = hasBody ? await req.arrayBuffer() : undefined; + + const upstream = await fetch(url, { + method: req.method, + headers, + body, + redirect: "manual", + }); + + // Mirror the upstream response (status + body + content-type) back to the browser, same-origin. + const resHeaders = new Headers(); + const ct = upstream.headers.get("content-type"); + if (ct) resHeaders.set("content-type", ct); + return new Response(upstream.body, { + status: upstream.status, + statusText: upstream.statusText, + headers: resHeaders, + }); +} diff --git a/nexus-web/test/dev-proxy.test.ts b/nexus-web/test/dev-proxy.test.ts new file mode 100644 index 0000000..cfcab44 --- /dev/null +++ b/nexus-web/test/dev-proxy.test.ts @@ -0,0 +1,55 @@ +// Issue #22: on `next dev` the Studio prints `/mcp` for an agent (lib/admin.ts mcpEndpoint), and nothing +// served it. app/mcp proxies it to the API the way app/api/v1/[...path] proxies the API: Origin stripped, the bearer +// and body passed through, the answer mirrored; outside development both answer 404 and send nothing. +import { NextRequest } from "next/server"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { POST as mcpPost } from "../app/mcp/route"; +import { GET as apiGet } from "../app/api/v1/[...path]/route"; + +const upstream = vi.fn<(url: string, init?: RequestInit) => Promise>(async () => + new Response('{"jsonrpc":"2.0","id":1,"result":{}}', { status: 200, headers: { "content-type": "application/json", "x-internal": "1" } })); + +beforeEach(() => { + upstream.mockClear(); + vi.stubGlobal("fetch", upstream); + vi.stubEnv("DEV_API_PROXY_TARGET", "http://127.0.0.1:18090"); +}); +afterEach(() => { vi.unstubAllGlobals(); vi.unstubAllEnvs(); }); + +const mcpCall = () => new NextRequest("http://localhost:3000/mcp", { + method: "POST", + body: '{"jsonrpc":"2.0","id":1,"method":"tools/list"}', + headers: { authorization: "Bearer nxm_x", accept: "application/json, text/event-stream", origin: "http://localhost:3000", "content-type": "application/json" }, +}); + +describe("dev proxy", () => { + it("on next dev, /mcp reaches the API's /mcp with the bearer and body and without Origin", async () => { + vi.stubEnv("NODE_ENV", "development"); + const res = await mcpPost(mcpCall()); + expect(upstream).toHaveBeenCalledTimes(1); + const [url, init] = upstream.mock.calls[0]; + expect(url).toBe("http://127.0.0.1:18090/mcp"); + const sent = new Headers(init?.headers); + expect(sent.get("authorization")).toBe("Bearer nxm_x"); + expect(sent.get("accept")).toBe("application/json, text/event-stream"); + expect(sent.has("origin")).toBe(false); + expect(new TextDecoder().decode(init?.body as ArrayBuffer)).toContain("tools/list"); + expect(res.status).toBe(200); + expect(res.headers.get("content-type")).toBe("application/json"); + expect(res.headers.has("x-internal")).toBe(false); + expect(await res.text()).toContain('"result"'); + }); + + it("the API route keeps its path and query", async () => { + vi.stubEnv("NODE_ENV", "development"); + await apiGet(new NextRequest("http://localhost:3000/api/v1/admin/mcp-tokens?page=2"), { params: Promise.resolve({ path: ["admin", "mcp-tokens"] }) }); + expect(upstream.mock.calls[0][0]).toBe("http://127.0.0.1:18090/api/v1/admin/mcp-tokens?page=2"); + }); + + it("outside development both answer 404 and send nothing", async () => { + vi.stubEnv("NODE_ENV", "production"); + expect((await mcpPost(mcpCall())).status).toBe(404); + expect((await apiGet(new NextRequest("http://localhost:3000/api/v1/x"), { params: Promise.resolve({ path: ["x"] }) })).status).toBe(404); + expect(upstream).not.toHaveBeenCalled(); + }); +});