Compare commits
67
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
8134e2b890 | ||
|
|
f1405bd313 | ||
|
|
2eec714912 | ||
|
|
26d2063a1e | ||
|
|
84f8ade70c | ||
|
|
5ea7855e02 | ||
|
|
5201ae32c8 | ||
|
|
ca8c6ad940 | ||
|
|
ac9aa64ddb | ||
|
|
7a055f6bb8 | ||
|
|
45594304f8 | ||
|
|
1b67e70bf9 | ||
|
|
5535673f8d | ||
|
|
f0e658b4c2 | ||
|
|
053a916ada | ||
|
|
f2cc303b0c | ||
|
|
a8ed51d1a7 | ||
|
|
12e5ba818e | ||
|
|
066618dea5 | ||
|
|
1c175e7e8e | ||
|
|
b42c1e7e06 | ||
|
|
d6ffec3f41 | ||
|
|
a34cf4cf8a | ||
|
|
df1d6a72f6 | ||
|
|
7583b4cac1 | ||
|
|
fc5aa7860b | ||
|
|
2438ae7e9d | ||
|
|
bd1de5ac7a | ||
|
|
fdf733c686 | ||
|
|
12445a01fb | ||
|
|
ee16ec0542 | ||
|
|
cd80ba130e | ||
|
|
dc1e802922 | ||
|
|
7fd1d7ebf8 | ||
|
|
3661ef4fe3 | ||
|
|
6374f2fa1c | ||
|
|
4118708967 | ||
|
|
7ab7fe8b05 | ||
|
|
1aba01e40f | ||
|
|
9c28d5170f | ||
|
|
6cb86e0352 | ||
|
|
45410df6e7 | ||
|
|
fc53c68fee | ||
|
|
23b893cf9f | ||
|
|
cbd48e52fd | ||
|
|
6779921cd6 | ||
|
|
bda235f354 | ||
|
|
5930bc7b25 | ||
|
|
ef8decc892 | ||
|
|
a5b4b627a6 | ||
|
|
7da3741fe2 | ||
|
|
6f77495f29 | ||
|
|
61186648da | ||
|
|
d8ef6956f8 | ||
|
|
0053f1d609 | ||
|
|
e0ad832034 | ||
|
|
505be6e986 | ||
|
|
fcb7a5ee07 | ||
|
|
90dfb6869e | ||
|
|
5f3fe69d7e | ||
|
|
1b250e0a1c | ||
|
|
4e6ff0704f | ||
|
|
476befe4b4 | ||
|
|
debfdc5410 | ||
|
|
d10c15e6d3 | ||
|
|
abded9c5b1 | ||
|
|
b270ca81fc |
No files matched your search
+10
@@ -157,3 +157,13 @@ worldwideview.code-workspace
|
||||
/playwright-report/
|
||||
/test-results/
|
||||
/playwright/.auth/
|
||||
/.playwright-mcp/
|
||||
|
||||
# MCP client config -- contains a live API key, never commit
|
||||
.mcp.json
|
||||
|
||||
# Root-level UAT / debug scratch artifacts
|
||||
/uat-*.png
|
||||
/step*.png
|
||||
/mcp-test-*.png
|
||||
/api-keys-response.json
|
||||
@@ -0,0 +1,106 @@
|
||||
# WorldWideView
|
||||
|
||||
## What This Is
|
||||
|
||||
WorldWideView is a real-time geospatial intelligence engine that visualizes live global data on an interactive 3D globe -- controllable by any AI agent via a production MCP server. Built for power users, researchers, and developers who need a live, plugin-extensible view of the world and want to connect their AI tools directly to it.
|
||||
|
||||
## Core Value
|
||||
|
||||
A single globe that shows everything happening in the world right now, extensible by anyone via plugins, and controllable by any AI agent via MCP.
|
||||
|
||||
## Current State (v1.2 shipped 2026-05-30)
|
||||
|
||||
**What shipped in v1.2:**
|
||||
- Transport-agnostic personal API keys (wwv_prefix.secret bearer tokens)
|
||||
- Production MCP server at /api/mcp (Streamable HTTP, stateless, Bearer auth)
|
||||
- ConnectAgentHelper UI for one-copy-paste agent setup
|
||||
- Globe state MCP resources (globe://state, globe://sessions, globe://layers)
|
||||
- Globe control tools (pan_globe, focus_entity, toggle_layer, set_timeline) via SSE push
|
||||
- Data query tools (search_entities, get_entities_in_region, get_entity_details, get_plugin_data)
|
||||
- Plugin-contributed MCP tools via SDK manifest extension + frontend relay bridge
|
||||
|
||||
**Tech stack additions:** ioredis singleton, @modelcontextprotocol/sdk, ReadableStream SSE, Redis ZSET/LIST/SET for state/commands/catalog
|
||||
|
||||
## Current Milestone: v1.3 Location Intelligence
|
||||
|
||||
**Goal:** Extend the MCP server with geocoding, rich entity filtering, and entity favorites so AI agents can find places, drill into plugin data, and bookmark tracked objects.
|
||||
|
||||
**Target features:**
|
||||
- Geocoding + fly-to (2 new MCP tools: `geocode_location` + `fly_to`)
|
||||
- Entity filtering via MCP (generic baseline + plugin-declared filter extensions)
|
||||
- Entity favorites: `save_favorite`, `list_favorites`, `remove_favorite` (per-user, PostgreSQL-backed)
|
||||
|
||||
**Backlog (deferred):**
|
||||
- PLG-01/PLG-02: list_plugins() + install_plugin() marketplace tools (backlog 999.1/999.2)
|
||||
- UX-01: ConnectAgentHelper upgrade CTA in demo edition (backlog 999.3)
|
||||
|
||||
## Requirements
|
||||
|
||||
### Validated (Shipped)
|
||||
|
||||
**v1.0 Unified Auth Account System (Phases 1-11, shipped 2026-05-28)**
|
||||
- Supabase shared-cookie auth federation across worldwideview, marketplace, and web
|
||||
- OAuth (GitHub, Google) and email+password auth with NextAuth v5
|
||||
- Shared user identity via `NEXT_PUBLIC_WWV_COOKIE_DOMAIN` across three apps
|
||||
- JWT session persistence, auth callback redirect fix, linked accounts page
|
||||
- Legal/privacy compliance (ToS, cookie consent, GDPR data deletion flow)
|
||||
|
||||
**v1.1 Plugin Install Auth Gate (Phase 12 shipped 2026-05-28)**
|
||||
- PluginInstall model + migration + Plugin.installs counter
|
||||
- Fire-and-forget install tracking upsert in GET /api/install/start
|
||||
|
||||
**v1.2 Full MCP Support (Phases 16-21, shipped 2026-05-30)**
|
||||
- Transport-agnostic API keys with bcrypt storage and timing-oracle prevention - v1.2
|
||||
- Stateless MCP server (Streamable HTTP) with Bearer auth - v1.2
|
||||
- ConnectAgentHelper per-client setup UI; secret only in Authorization header - v1.2
|
||||
- Globe state as MCP resources backed by Redis with heartbeat TTL - v1.2
|
||||
- Globe command bridge via SSE push (< 100ms latency) - v1.2
|
||||
- Data query tools across all active plugins - v1.2
|
||||
- Plugin-contributed namespaced MCP tools via frontend relay - v1.2
|
||||
|
||||
### Active (v1.3 Location Intelligence)
|
||||
|
||||
- [ ] geocode_location(query) MCP tool returning {lat, lng, name, bbox} via Nominatim/OSM
|
||||
- [ ] fly_to(lat, lng, altitude?) MCP tool panning globe camera via SSE command bridge
|
||||
- [ ] Generic entity filters (type, region, timeRange, status) via MCP set_filter/clear_filter
|
||||
- [ ] Plugin-declared filter manifest extension + get_plugin_filters(pluginId) MCP tool
|
||||
- [ ] UserFavorite Prisma model + save_favorite / list_favorites / remove_favorite MCP tools
|
||||
|
||||
### Out of Scope
|
||||
|
||||
- Embedding an AI chat UI inside the globe -- MCP is server-only
|
||||
- Browser-side MCP client -- globe is an MCP server target, not client
|
||||
- Playwright/computer-use globe control -- using SSE command bridge
|
||||
- Stdio-only MCP transport -- HTTP/SSE for production deployability
|
||||
- CLI tool -- API + MCP cover v1.2; CLI is additive and non-blocking
|
||||
- API key scopes/permissions and rotation/grace-period flows -- revisit later
|
||||
- OAuth 2.1 for MCP auth -- personal API keys sufficient for v1.2
|
||||
|
||||
## Context
|
||||
|
||||
- **Three apps**: worldwideview (Next.js globe), worldwideview-marketplace (plugin store), worldwideview-web (marketing)
|
||||
- **Auth**: NextAuth v5 + Supabase shared cookies, auth host at worldwideview.dev
|
||||
- **State**: 9 Zustand slices (globe, layers, timeline, ui, filter, data, config, favorites, geojson)
|
||||
- **MCP**: Stateless Streamable HTTP at /api/mcp; Redis for state/commands/catalog; 8 tools + 3 resources
|
||||
- **Data pipeline**: wwv-data-engine (Fastify + Redis) + plugin seeders
|
||||
- **Plugin SDK**: `@worldwideview/wwv-plugin-sdk` with mcpTools manifest extension
|
||||
|
||||
## Key Decisions
|
||||
|
||||
| Decision | Rationale | Outcome |
|
||||
|----------|-----------|---------|
|
||||
| Supabase shared-cookie auth federation | Single sign-on across 3 Next.js apps | ✓ Good |
|
||||
| JWT install bridge for plugin installs | Instance-level auth keeps globe secure | ✓ Good |
|
||||
| HTTP/SSE Streamable HTTP for MCP | Production deployable, any AI client | ✓ Good |
|
||||
| Redis for all MCP state (no in-process) | Scales to multi-user cloud deployment | ✓ Good |
|
||||
| SSE push over WebSocket | Zero infra change, App Router native, MCP spec-first | ✓ Good |
|
||||
| Plugin tools via frontend relay | worldwideview-only, no engine endpoint, composable | ✓ Good |
|
||||
| Generic transport-agnostic API keys | One bearer key for MCP + future REST | ✓ Good |
|
||||
| Marketplace tools deferred to v1.3 | Kept v1.2 worldwideview-only; clean scope | ✓ Good |
|
||||
|
||||
## Evolution
|
||||
|
||||
This document evolves at phase transitions and milestone boundaries.
|
||||
|
||||
---
|
||||
*Last updated: 2026-05-31 after v1.3 milestone start*
|
||||
@@ -0,0 +1,96 @@
|
||||
# Requirements: WorldWideView v1.3
|
||||
|
||||
**Defined:** 2026-05-31
|
||||
**Core Value:** A single globe that shows everything happening in the world right now, extensible by anyone via plugins, and controllable by any AI agent via MCP.
|
||||
|
||||
## v1.3 Requirements
|
||||
|
||||
### Geocoding
|
||||
|
||||
- [ ] **GEO-01**: Agent can call `geocode_location(query)` and receive 2-5 ranked results with `{lat, lng, name, type, country, bbox, importance}` via Nominatim
|
||||
- [x] **GEO-02**: Agent can call `fly_to(lat, lng, altitude?, bbox?)` to pan/zoom the globe camera; when `bbox` is provided, Cesium fits the region to the bounding box
|
||||
- [x] **GEO-03**: Geocoding enforces a server-side 1 req/sec Redis sliding window rate limiter and caches results for 24 hours to prevent Nominatim IP ban
|
||||
|
||||
### Filtering
|
||||
|
||||
- [x] **FILT-01**: Agent can call `set_filter(pluginId, filters)` to push a live filter to the globe via the SSE command bridge; browser applies it to Zustand filterSlice
|
||||
- [x] **FILT-02**: Agent can call `clear_filter(pluginId?)` to remove all active filters or per-plugin filters via SSE bridge
|
||||
- [x] **FILT-03**: Agent can call `get_plugin_filters(pluginId)` to retrieve filterable fields declared by a plugin via session catalog extension
|
||||
- [x] **FILT-04**: Agent can pass optional `filters` params to the existing `search_entities` tool to receive pre-filtered results inline (no set_filter state dependency)
|
||||
|
||||
### Favorites
|
||||
|
||||
- [ ] **FAV-01**: Agent can call `save_favorite(entityId, pluginId, name?)` to bookmark a tracked entity per-user (upsert on existing `Favorite` Prisma model)
|
||||
- [ ] **FAV-02**: Agent can call `list_favorites()` to retrieve saved entities with `status: "live" | "stale"` (stale = entity not currently in data stream)
|
||||
- [ ] **FAV-03**: Agent can call `remove_favorite(entityId, pluginId)` to delete a saved bookmark
|
||||
|
||||
### Safety & Guards
|
||||
|
||||
- [x] **SAFE-01**: All new MCP tool registrars check `isDemo` gate before `authenticateApiKey()`, consistent with v1.2 pattern
|
||||
- [ ] **SAFE-02**: MCP favorites tools call `prisma.favorite` directly and never proxy through the REST `/api/user/favorites` route (which uses NextAuth cookie auth and silently 401s on API key requests)
|
||||
|
||||
### Integration
|
||||
|
||||
- [ ] **INTG-01**: All v1.3 tool registrars (geocoding, favorites, filtering) are wired into the MCP POST handler; `tools/list` exposes all 8 new tools
|
||||
- [ ] **INTG-02**: `MCP_SERVER_VERSION` constant is bumped to `"1.3.0"` and reflected in every `initialize` response `serverInfo.version`
|
||||
|
||||
### Documentation
|
||||
|
||||
- [ ] **DOC-01**: Each v1.3 MCP tool has a complete tool-level description in its registrar (input schema, output shape, error codes, usage example) so it is self-documenting via `tools/list`
|
||||
- [ ] **DOC-02**: A developer guide exists explaining how to declare filterable fields in a plugin manifest (`filterDefinitions` extension) with a worked example
|
||||
- [ ] **DOC-03**: The user-facing ConnectAgentHelper or a companion doc describes all v1.3 capabilities available to connected agents (geocoding, filtering, favorites)
|
||||
- [ ] **DOC-04**: A changelog / release notes entry is written for v1.3 covering the 8 new MCP tools, 2 integration changes, and 1 search enhancement
|
||||
|
||||
## Future Requirements (v1.4+)
|
||||
|
||||
### Marketplace Tools (Backlog)
|
||||
- **PLG-01**: Agent can call `list_plugins()` to browse available marketplace plugins
|
||||
- **PLG-02**: Agent can call `install_plugin(pluginId)` to install a marketplace plugin
|
||||
- **UX-01**: ConnectAgentHelper shows upgrade CTA in demo edition
|
||||
|
||||
### Geocoding Enhancements
|
||||
- Reverse geocoding: coordinates to address
|
||||
- Structured address input (street, city, country)
|
||||
- Provider fallback (Photon, OpenCage)
|
||||
|
||||
## Out of Scope
|
||||
|
||||
| Feature | Reason |
|
||||
|---------|--------|
|
||||
| Reverse geocoding | Not in v1.3 goals; forward search sufficient |
|
||||
| Filter state persisted in Redis | Zustand is single source of truth; SSE push only |
|
||||
| search_entities as a new filtered tool | Extended existing tool with optional filters instead |
|
||||
| MCP favorites REST proxy | Architecture invariant: API key auth != cookie auth |
|
||||
| OAuth 2.1 for MCP auth | Personal API keys sufficient |
|
||||
|
||||
## Traceability
|
||||
|
||||
| Requirement | Phase | Status |
|
||||
|-------------|-------|--------|
|
||||
| GEO-01 | Phase 22 | Pending |
|
||||
| GEO-02 | Phase 22 | Complete |
|
||||
| GEO-03 | Phase 22 | Complete |
|
||||
| FAV-01 | Phase 22 | Pending |
|
||||
| FAV-02 | Phase 22 | Pending |
|
||||
| FAV-03 | Phase 22 | Pending |
|
||||
| SAFE-01 | Phase 22 | Complete |
|
||||
| SAFE-02 | Phase 22 | Pending |
|
||||
| FILT-01 | Phase 23 | Complete |
|
||||
| FILT-02 | Phase 23 | Complete |
|
||||
| FILT-03 | Phase 23 | Complete |
|
||||
| FILT-04 | Phase 23 | Complete |
|
||||
| INTG-01 | Phase 24 | Pending |
|
||||
| INTG-02 | Phase 24 | Pending |
|
||||
| DOC-01 | Phase 25 | Pending |
|
||||
| DOC-02 | Phase 25 | Pending |
|
||||
| DOC-03 | Phase 25 | Pending |
|
||||
| DOC-04 | Phase 25 | Pending |
|
||||
|
||||
**Coverage:**
|
||||
- v1.3 requirements: 18 total
|
||||
- Mapped to phases: 18
|
||||
- Unmapped: 0 ✓
|
||||
|
||||
---
|
||||
*Requirements defined: 2026-05-31*
|
||||
*Last updated: 2026-05-31 after Phase 25 documentation phase added*
|
||||
@@ -0,0 +1,114 @@
|
||||
# Roadmap: WorldWideView
|
||||
|
||||
## Milestones
|
||||
|
||||
- [x] **v1.2 Full MCP Support** - Phases 16-21 (shipped 2026-05-30) - [archive](milestones/v1.2-ROADMAP.md)
|
||||
- [x] **v1.3 Location Intelligence** - Phases 22-25 (completed 2026-05-31)
|
||||
|
||||
## Phases
|
||||
|
||||
<details>
|
||||
<summary>v1.2 Full MCP Support (Phases 16-21) - SHIPPED 2026-05-30</summary>
|
||||
|
||||
- [x] Phase 16: API Key Auth Foundation (4/4 plans) - completed 2026-05-29
|
||||
- [x] Phase 17: MCP Server Foundation (3/3 plans) - completed 2026-05-30
|
||||
- [x] Phase 18: Globe State Sync + Sessions (4/4 plans + gap-closure) - completed 2026-05-30
|
||||
- [x] Phase 19a: Globe Command Bridge poll-based (3/3 plans) - completed 2026-05-30
|
||||
- [x] Phase 19b: SSE Push Transport (2/2 plans) - completed 2026-05-30
|
||||
- [x] Phase 20: Data Query Tools (4/4 plans) - completed 2026-05-30
|
||||
- [x] Phase 21: Plugin-Contributed Tools + Quality (5/5 plans) - completed 2026-05-30
|
||||
|
||||
Full details: [milestones/v1.2-ROADMAP.md](milestones/v1.2-ROADMAP.md)
|
||||
|
||||
</details>
|
||||
|
||||
### v1.3 Location Intelligence
|
||||
|
||||
- [x] **Phase 22: Geocoding + Favorites** - Geocode places, fly the globe, bookmark tracked entities (4/4 plans, verified 2026-05-31)
|
||||
- [x] **Phase 23: Entity Filtering** - Push live filters to the globe and query plugin-declared filter schemas
|
||||
- [x] **Phase 24: Route Wiring + Version Bump** - Wire all v1.3 registrars into the MCP handler and ship MCP_SERVER_VERSION 1.3.0
|
||||
- [x] **Phase 25: Documentation** - MCP tool docs, plugin author filter guide, user-facing capability summary, and v1.3 release notes (1/1 plans, completed 2026-05-31)
|
||||
|
||||
## Phase Details
|
||||
|
||||
### Phase 22: Geocoding + Favorites
|
||||
**Goal**: AI agents can find any place on Earth by name, fly the globe camera to it, and bookmark tracked entities for later retrieval
|
||||
**Depends on**: Phase 21 (v1.2 SSE command bridge, authenticateApiKey, Redis, Prisma Favorite model)
|
||||
**Requirements**: GEO-01, GEO-02, GEO-03, FAV-01, FAV-02, FAV-03, SAFE-01, SAFE-02
|
||||
**Success Criteria** (what must be TRUE):
|
||||
1. Agent calls `geocode_location("Paris")` and receives ranked results with lat/lng/name/bbox without triggering Nominatim rate limits across repeated calls
|
||||
2. Agent calls `fly_to(48.85, 2.35)` and the live globe camera pans to that coordinate within SSE push latency (< 100ms)
|
||||
3. Agent calls `save_favorite`, then `list_favorites`, and the saved entity appears with a `status` field reflecting whether it is currently live in the data stream
|
||||
4. Agent calls `remove_favorite` and the entry is gone from subsequent `list_favorites` responses
|
||||
5. All new tools return a structured error (not 500) when called in demo edition, consistent with v1.2 isDemo gate behavior
|
||||
**Plans**: TBD
|
||||
|
||||
### Phase 23: Entity Filtering
|
||||
**Goal**: AI agents can push live filters to the globe and discover what filter fields each plugin exposes
|
||||
**Depends on**: Phase 22 (isDemo + authenticateApiKey patterns established, GlobeCommand type in Redis/SSE bridge)
|
||||
**Requirements**: FILT-01, FILT-02, FILT-03, FILT-04
|
||||
**Success Criteria** (what must be TRUE):
|
||||
1. Agent calls `set_filter("flights", { status: "airborne" })` and the globe immediately hides non-airborne entities without a page reload
|
||||
2. Agent calls `clear_filter()` with no arguments and all active plugin filters are removed from the globe in one command
|
||||
3. Agent calls `get_plugin_filters("flights")` and receives the filterable fields declared in that plugin's session catalog entry
|
||||
4. Agent passes `filters` to the existing `search_entities` call and receives only matching results, with no dependency on prior `set_filter` state
|
||||
**Plans**: 3 plans (ships atomically per STATE.md)
|
||||
- [x] 23-01-PLAN.md — Foundation: GlobeCommand setFilter/clearFilter variants + validator, bridge dispatch into filterSlice, shared filterValueSchema, matchFilterValue extraction, catalog filterDefinitions, RED tool stubs (wave 1, TDD)
|
||||
- [x] 23-02-PLAN.md — Filter MCP tools (set_filter, clear_filter, get_plugin_filters), search_entities filters param on properties, catalog publisher emits filterDefinitions (wave 2, TDD)
|
||||
- [x] 23-03-PLAN.md — Wire registerFilterTools into the MCP route + atomic phase integration verification (wave 3)
|
||||
|
||||
### Phase 24: Route Wiring + Version Bump
|
||||
**Goal**: All v1.3 tools are reachable via the production MCP endpoint and the server self-reports version 1.3.0
|
||||
**Depends on**: Phase 22, Phase 23 (all registrars implemented)
|
||||
**Requirements**: INTG-01 (integration wiring), INTG-02 (version bump)
|
||||
**Success Criteria** (what must be TRUE):
|
||||
1. MCP `tools/list` response includes all v1.3 tools: `geocode_location`, `fly_to`, `save_favorite`, `list_favorites`, `remove_favorite`, `set_filter`, `clear_filter`, `get_plugin_filters`
|
||||
2. MCP server `serverInfo.version` field returns `"1.3.0"` on every initialize handshake
|
||||
3. `search_entities` with optional `filters` param is reflected in the tool schema exposed to clients
|
||||
**Plans**: 24-01 (COMPLETE) - INTG-01 verified, INTG-02 shipped (MCP_SERVER_VERSION 1.3.0)
|
||||
**Status**: COMPLETE 2026-05-31. tsc clean, 750 Vitest tests GREEN (+12), build OK. Commits 5201ae3, 5ea7855.
|
||||
|
||||
### Phase 25: Documentation
|
||||
**Goal**: Every v1.3 feature is fully documented for three audiences: MCP clients (tool schemas), plugin developers (filter manifest guide), and end users (capability summary)
|
||||
**Depends on**: Phase 24 (all tools shipped and wired; final tool schemas stable)
|
||||
**Requirements**: DOC-01, DOC-02, DOC-03, DOC-04
|
||||
**Success Criteria** (what must be TRUE):
|
||||
1. Every v1.3 MCP tool description in `registerGeocodingTools`, `registerFavoritesTools`, `registerFilterTools` includes: what it does, all input params with types, the output shape, and at least one usage example
|
||||
2. A `docs/plugin-filter-guide.md` (or equivalent) explains how a plugin author declares `filterDefinitions` in their manifest with a complete worked example for a hypothetical flights plugin
|
||||
3. ConnectAgentHelper or a linked doc lists all v1.3 tools an agent can call, with a plain-English description of each capability
|
||||
4. A v1.3 changelog entry (in `CHANGELOG.md` or the PR body) lists all 8 new MCP tools, the `search_entities` filter enhancement, and the version bump to 1.3.0
|
||||
**Plans**: 25-01 (COMPLETE) - DOC-01..04 closed.
|
||||
**Status**: COMPLETE 2026-05-31. Enriched all 8 v1.3 tool descriptions (DOC-01), added docs/plugin-filter-guide.md (DOC-02), listed all tools in ConnectAgentHelper (DOC-03), added CHANGELOG.md v1.3.0 entry (DOC-04). tsc clean, 750 Vitest tests GREEN, build OK. Commits 84f8ade, 26d2063, 2eec714, f1405bd.
|
||||
|
||||
## Progress Table
|
||||
|
||||
| Phase | Plans Complete | Status | Completed |
|
||||
|-------|----------------|--------|-----------|
|
||||
| 22. Geocoding + Favorites | 4/4 | Complete | 2026-05-31 |
|
||||
| 23. Entity Filtering | 3/3 | Complete | 2026-05-31 |
|
||||
| 24. Route Wiring + Version Bump | 1/1 | Complete | 2026-05-31 |
|
||||
| 25. Documentation | 1/1 | Complete | 2026-05-31 |
|
||||
|
||||
## Backlog
|
||||
|
||||
Per the 21-REPLAN locked decision ("NO marketplace" in v1.2 scope), the two marketplace
|
||||
plugin-management MCP tools were deferred. They require the marketplace JWT install bridge,
|
||||
which was descoped to keep v1.2 worldwideview-only.
|
||||
|
||||
- **999.1 -- PLG-01: `list_plugins()` MCP tool** -- returns all marketplace plugins with
|
||||
install status for the authenticated user. Depends on marketplace API + JWT bridge.
|
||||
- **999.2 -- PLG-02: `install_plugin({ pluginSlug })` MCP tool** -- triggers installation via
|
||||
the existing marketplace JWT bridge flow. Depends on PLG-01 + marketplace install endpoint.
|
||||
|
||||
- **999.3 -- UX-01: Show MCP / ConnectAgentHelper as "Cloud edition" upgrade CTA in demo** --
|
||||
Currently `!isDemo` in Header.tsx:449 hides the entire ConnectAgentHelper section in demo.
|
||||
UX improvement: surface it as a locked/teaser CTA that explains the feature and links to
|
||||
upgrade. Pairs with v1.3 MCP-OBSERVATIONS.md scope (geocoding, OSM search, basemap control,
|
||||
entity filtering, enhanced search, favorites, plugin-tool discovery).
|
||||
|
||||
Also tracked as partials (functional, refinement deferred):
|
||||
- **CTRL-02** focus_entity entityId-only resolution -- currently a no-op without lat/lng;
|
||||
needs entity-id -> coordinate lookup wired into the command dispatch.
|
||||
- **MCP-QA-03** explicit Redis reconnect test -- stateless SSE arch makes the original
|
||||
WebSocket-subscriber spec N/A; ioredis auto-reconnects. Add a reconnect test if reliability
|
||||
concerns arise.
|
||||
@@ -0,0 +1,65 @@
|
||||
---
|
||||
gsd_state_version: 1.0
|
||||
milestone: v1.3
|
||||
milestone_name: Location Intelligence
|
||||
status: complete
|
||||
last_updated: "2026-05-31T01:40:00.000Z"
|
||||
last_activity: 2026-05-31
|
||||
progress:
|
||||
total_phases: 4
|
||||
completed_phases: 4
|
||||
total_plans: 9
|
||||
completed_plans: 9
|
||||
percent: 100
|
||||
---
|
||||
|
||||
# Project State
|
||||
|
||||
## Project Reference
|
||||
|
||||
See: .planning/PROJECT.md (updated 2026-05-31)
|
||||
|
||||
**Core value:** A single globe that shows everything happening in the world right now, extensible by anyone via plugins, and controllable by any AI agent via MCP.
|
||||
**Current focus:** Phase 25 — documentation
|
||||
|
||||
## Current Position
|
||||
|
||||
Phase: 25 (documentation) - COMPLETE
|
||||
Plan: 1 of 1 (25-01 landed)
|
||||
Status: Phase 25 COMPLETE - DOC-01..04 closed. Enriched all 8 v1.3 MCP tool descriptions, added docs/plugin-filter-guide.md, listed all tools in ConnectAgentHelper, added CHANGELOG.md v1.3.0 entry. tsc clean, 750 Vitest tests GREEN, build OK. Commits 84f8ade, 26d2063, 2eec714, f1405bd. Milestone v1.3 Location Intelligence COMPLETE (4 of 4 phases).
|
||||
Last activity: 2026-05-31
|
||||
Resume file: None
|
||||
|
||||
Progress: [##########] 100% (4 of 4 phases complete)
|
||||
|
||||
## Key Decisions (carried from v1.2)
|
||||
|
||||
- **MCP transport:** Stateless Streamable HTTP at /api/mcp; raw @modelcontextprotocol/sdk; Bearer auth via authenticateApiKey(). No custom server.ts.
|
||||
- **Redis for ephemeral state:** Globe state, command queues, session catalogs all in Redis. PostgreSQL for user-owned persistent data.
|
||||
- **SSE command bridge:** EventSource-based push (GET /api/globe/commands/stream). Reuse for fly_to in v1.3.
|
||||
- **Plugin tools via frontend relay:** No engine endpoint. useMcpCatalogPublisher + useMcpRelayBridge pattern.
|
||||
- **Three editions:** NEXT_PUBLIC_WWV_EDITION (local/cloud/demo). isDemo gate runs before auth on all new endpoints.
|
||||
- **Generic API keys:** wwv_prefix.secret bearer tokens. authenticateApiKey() middleware reused for all new MCP tools.
|
||||
|
||||
## v1.3 Phase Map
|
||||
|
||||
| Phase | Goal | Key requirements |
|
||||
|-------|------|-----------------|
|
||||
| 22 | Geocoding + Favorites | GEO-01..03, FAV-01..03, SAFE-01..02 |
|
||||
| 23 | Entity Filtering | FILT-01..04 |
|
||||
| 24 | Route Wiring + Version Bump | INTG-01, INTG-02 |
|
||||
| 25 | Documentation | DOC-01..04 |
|
||||
|
||||
## Blockers
|
||||
|
||||
None.
|
||||
|
||||
## Accumulated Context
|
||||
|
||||
- v1.2 archived at .planning/milestones/v1.2-* and tagged v1.2 in git.
|
||||
- PR #215 (feat/mcp-support) open on GitHub, awaiting merge.
|
||||
- Phase numbering continues from v1.2's last phase (21). v1.3 starts at Phase 22.
|
||||
- Phase 23 (Entity Filtering) must ship atomically: GlobeCommand type extensions + catalog changes + all 4 FILT tools are coupled. Do not split.
|
||||
- Phase 24 is purely mechanical wiring (no new logic); can proceed immediately after 22 and 23 complete.
|
||||
- Nominatim integration: server-side rate limiter (1 req/sec Redis sliding window) + 24h result cache are mandatory before any geocoding tool goes live (GEO-03).
|
||||
- Favorites use prisma.favorite directly -- never proxy through /api/user/favorites (cookie auth incompatible with API key sessions, SAFE-02).
|
||||
@@ -0,0 +1,94 @@
|
||||
---
|
||||
phase: 16-api-key-auth-foundation
|
||||
plan: "03"
|
||||
subsystem: api-key-auth
|
||||
tags: [api-keys, crud-routes, auth, ownership-scoping, reveal-once]
|
||||
dependency_graph:
|
||||
requires: ["16-01", "16-02"]
|
||||
provides: ["16-04"]
|
||||
affects: []
|
||||
tech_stack:
|
||||
added: []
|
||||
patterns:
|
||||
- "isDemo gate before session check on all handlers"
|
||||
- "deleteMany for atomic ownership-scoped hard delete (BOLA prevention)"
|
||||
- "P2002 prefix-collision retry on create"
|
||||
- "reveal-once fullToken in 201 body only"
|
||||
key_files:
|
||||
created:
|
||||
- src/app/api/api-keys/route.ts
|
||||
- src/app/api/api-keys/[id]/route.ts
|
||||
modified: []
|
||||
decisions:
|
||||
- "userId always taken from session.user.id, never from request body (T-16-09)"
|
||||
- "isDemo gate runs FIRST before auth() in all three handlers (Pitfall 6 - demo has no DB row)"
|
||||
- "createKeyWithRetry helper isolates P2002 catch so outer handler catch-all remains clean"
|
||||
- "deleteMany (not delete) used to avoid Prisma NotFound throw on foreign key - returns count 0 instead (TOCTOU elimination)"
|
||||
metrics:
|
||||
duration: "~12 minutes"
|
||||
completed_date: "2026-05-29"
|
||||
tasks_completed: 2
|
||||
tasks_total: 2
|
||||
files_created: 2
|
||||
files_modified: 0
|
||||
---
|
||||
|
||||
# Phase 16 Plan 03: API Key CRUD Route Handlers Summary
|
||||
|
||||
## One-liner
|
||||
|
||||
GET/POST/DELETE route handlers for `/api/api-keys` with ownership-scoped revoke, max-3 enforcement, and reveal-once fullToken in the 201 response.
|
||||
|
||||
## What Was Built
|
||||
|
||||
Three HTTP handlers completing the Wave 2 server surface:
|
||||
|
||||
**`src/app/api/api-keys/route.ts`** (GET + POST)
|
||||
- GET: lists the session user's keys selecting only `{ id, name, prefix, createdAt, lastUsedAt }` - `hashedSecret` never included in response
|
||||
- POST: enforces max-3 (422 `max_keys_reached`), calls `generateApiKey()`, creates the row via Prisma, handles P2002 prefix collision with a single retry, returns 201 `{ key: { id, name, createdAt, fullToken } }` - fullToken returned exactly once here, never again
|
||||
|
||||
**`src/app/api/api-keys/[id]/route.ts`** (DELETE)
|
||||
- `deleteMany({ where: { id, userId } })` - atomic ownership scoping; a foreign or missing key yields `count 0` -> 404, never a 500 or accidental deletion of another user's key
|
||||
|
||||
Both files apply the isDemo gate (403) before `auth()` on every handler, per Pitfall 6 (the demo virtual admin has no DB row).
|
||||
|
||||
## Tasks Completed
|
||||
|
||||
| Task | Name | Commit | Files |
|
||||
|------|------|--------|-------|
|
||||
| 1 | Implement GET + POST route.ts | 476befe | src/app/api/api-keys/route.ts |
|
||||
| 2 | Implement DELETE [id]/route.ts | 4e6ff07 | src/app/api/api-keys/[id]/route.ts |
|
||||
|
||||
## Test Results
|
||||
|
||||
- `pnpm test -- --run src/app/api/api-keys/route.test.ts`: 6/6 GREEN
|
||||
- `pnpm test -- --run "src/app/api/api-keys/[id]/route.test.ts"`: 4/4 GREEN
|
||||
- Full suite `pnpm test -- --run`: 403/403 GREEN (56 test files, no regressions)
|
||||
|
||||
## Security Invariants Verified
|
||||
|
||||
| Threat ID | Disposition | Verification |
|
||||
|-----------|-------------|--------------|
|
||||
| T-16-06 (BOLA - foreign key delete) | mitigated | deleteMany where clause tested in [id]/route.test.ts "ownership enforcement" test |
|
||||
| T-16-07 (hashedSecret/fullToken in list) | mitigated | "response never contains hashedSecret field" test asserts this; GET select projection omits it |
|
||||
| T-16-08 (demo gate) | mitigated | isDemo check is first line of all three handlers |
|
||||
| T-16-09 (userId from body) | mitigated | userId always `session.user.id`, never read from request body |
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
None - plan executed exactly as written.
|
||||
|
||||
## Known Stubs
|
||||
|
||||
None.
|
||||
|
||||
## Threat Flags
|
||||
|
||||
None - no new network surface beyond the planned routes.
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- `src/app/api/api-keys/route.ts` exists: FOUND
|
||||
- `src/app/api/api-keys/[id]/route.ts` exists: FOUND
|
||||
- Commit 476befe exists: FOUND
|
||||
- Commit 4e6ff07 exists: FOUND
|
||||
@@ -0,0 +1,99 @@
|
||||
---
|
||||
phase: 18-globe-state-sync
|
||||
plan: "05"
|
||||
subsystem: api-route-security
|
||||
tags: [security, demo-gate, gap-closure, rsrc-01]
|
||||
dependency_graph:
|
||||
requires: []
|
||||
provides: [isDemo-gate-on-globe-state-post]
|
||||
affects: [src/app/api/globe/state/route.ts, src/app/api/globe/state/route.test.ts]
|
||||
tech_stack:
|
||||
added: []
|
||||
patterns: [vi.hoisted-mutable-mock, isDemo-gate-before-auth]
|
||||
key_files:
|
||||
created: []
|
||||
modified:
|
||||
- src/app/api/globe/state/route.ts
|
||||
- src/app/api/globe/state/route.test.ts
|
||||
decisions:
|
||||
- "vi.hoisted() required for editionMock because vi.mock factories are hoisted above const declarations"
|
||||
- "isDemo gate placed after rate limiter and before userId resolution (matching canonical api-keys pattern)"
|
||||
- "useGlobeStateSync requires no code change: fetch only catches thrown exceptions, not HTTP 4xx responses"
|
||||
metrics:
|
||||
duration: "8 minutes"
|
||||
completed: "2026-05-30"
|
||||
tasks_completed: 2
|
||||
tasks_total: 2
|
||||
---
|
||||
|
||||
# Phase 18 Plan 05: isDemo Gate for POST /api/globe/state Summary
|
||||
|
||||
**One-liner:** Added isDemo edition gate (403 before auth) to POST /api/globe/state, closing GAP-01 identified in the PR #215 pre-merge audit.
|
||||
|
||||
## Tasks Completed
|
||||
|
||||
| Task | Name | Commit | Files |
|
||||
|------|------|--------|-------|
|
||||
| 1 | Add isDemo gate + test | ee16ec0 | route.ts, route.test.ts |
|
||||
| 2 | Verify useGlobeStateSync handles 403 gracefully | (no commit - read-only verification) | useGlobeStateSync.ts |
|
||||
|
||||
## What Was Built
|
||||
|
||||
**GAP-01 closed:** `POST /api/globe/state` previously had no demo-edition gate, allowing demo users to write globe state to Redis. The fix:
|
||||
|
||||
1. `route.ts`: Added `import { isDemo } from "@/core/edition"` and an early-return guard immediately after the rate limiter check and before the `userId` resolution block. Returns `{ error: "Not available in demo edition" }` with HTTP 403.
|
||||
|
||||
2. `route.test.ts`: Added `editionMock` via `vi.hoisted()` (required because `vi.mock` factories are hoisted above normal `const` declarations), a `vi.mock("@/core/edition", () => editionMock)` call, reset `editionMock.isDemo = false` in the existing `beforeEach`, and a new describe block "POST /api/globe/state -- demo edition gate" with one test asserting 403 + correct body + `writeGlobeState` not called.
|
||||
|
||||
**Task 2 - verification only:** `useGlobeStateSync.pushState` wraps `fetch` in a `try/catch` that only catches thrown exceptions (network errors). HTTP 403 responses are awaited and silently discarded because the hook never inspects `response.ok` or `response.status`. No code change was required.
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 1 - Bug] vi.hoisted() required for editionMock**
|
||||
- **Found during:** Task 1 (test run)
|
||||
- **Issue:** The plan suggested `const editionMock = { isDemo: false }` declared at module scope, but Vitest hoists `vi.mock` calls above all `const` declarations. The mock factory referenced `editionMock` before it was initialized, causing `ReferenceError: Cannot access 'editionMock' before initialization`.
|
||||
- **Fix:** Wrapped the declaration in `vi.hoisted()`: `const editionMock = vi.hoisted(() => ({ isDemo: false }))`. This runs the factory function before hoisting resolves, making the variable available to the `vi.mock` factory.
|
||||
- **Files modified:** `src/app/api/globe/state/route.test.ts`
|
||||
- **Commit:** ee16ec0
|
||||
|
||||
## Test Results
|
||||
|
||||
All 6 tests passed (5 pre-existing + 1 new):
|
||||
|
||||
```
|
||||
POST /api/globe/state (RSRC-01)
|
||||
- returns 200 and calls writeGlobeState with valid auth + body
|
||||
- returns 401 and does NOT call writeGlobeState when auth returns null
|
||||
- returns 400 and does NOT call writeGlobeState when sessionId is missing
|
||||
- returns 400 when snapshot is missing from body
|
||||
- still yields 200 when writeGlobeState rejects (fire-and-forget contract)
|
||||
POST /api/globe/state -- demo edition gate
|
||||
- returns 403 and does NOT call writeGlobeState when isDemo is true
|
||||
```
|
||||
|
||||
TypeScript strict mode: zero errors (`pnpm tsc --noEmit`).
|
||||
|
||||
## Threat Model Coverage
|
||||
|
||||
| Threat ID | Mitigation | Status |
|
||||
|-----------|-----------|--------|
|
||||
| T-18-05-01 | isDemo gate before auth prevents demo users writing state even with a valid session | MITIGATED |
|
||||
| T-18-05-02 | 403 returned before writeGlobeState is called; no Redis write occurs on demo edition | MITIGATED |
|
||||
|
||||
## Known Stubs
|
||||
|
||||
None.
|
||||
|
||||
## Threat Flags
|
||||
|
||||
None - this plan closes a security gap rather than introducing new surface.
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- [x] `src/app/api/globe/state/route.ts` modified - `isDemo` import and guard present
|
||||
- [x] `src/app/api/globe/state/route.test.ts` modified - new describe block present
|
||||
- [x] Commit ee16ec0 exists in git log
|
||||
- [x] 6/6 tests green
|
||||
- [x] tsc --noEmit: zero errors
|
||||
@@ -0,0 +1,48 @@
|
||||
# Changelog
|
||||
|
||||
All notable changes to WorldWideView are documented here. This project follows
|
||||
Conventional Commits and bumps semver in `package.json` per change.
|
||||
|
||||
## v1.3.0 - Location Intelligence (2026-05-31)
|
||||
|
||||
AI agents can now find places on Earth, fly the globe camera, bookmark entities,
|
||||
and filter the live globe over MCP. The MCP server reports version `1.3.0`
|
||||
(`MCP_SERVER_VERSION` bumped 1.2.0 -> 1.3.0).
|
||||
|
||||
### New MCP tools (8)
|
||||
|
||||
Geocoding and camera (`src/app/api/mcp/geocodingTools.ts`):
|
||||
|
||||
- `geocode_location` - resolve a place name or address to coordinates and a bounding
|
||||
box via OpenStreetMap Nominatim (per-user rate limit + 24h Redis cache).
|
||||
- `fly_to` - fly the live globe camera to a coordinate or bounding box over the SSE bridge.
|
||||
|
||||
Favorites (`src/app/api/mcp/favoritesTools.ts`):
|
||||
|
||||
- `save_favorite` - bookmark an entity (upsert by entityId).
|
||||
- `list_favorites` - list the user's bookmarks, each with a live/stale liveness status.
|
||||
- `remove_favorite` - delete a bookmarked entity.
|
||||
|
||||
Live filtering (`src/app/api/mcp/filterTools.ts`):
|
||||
|
||||
- `set_filter` - apply filters to a plugin's layer on the live globe (no page reload).
|
||||
- `clear_filter` - clear one plugin's filters, or all filters in one command.
|
||||
- `get_plugin_filters` - read a plugin's declared filterable fields.
|
||||
|
||||
### Enhancements
|
||||
|
||||
- `search_entities` gained an optional `filters` param (`src/lib/mcp/tools.ts`),
|
||||
keyed by entity property key, to return only matching entities independent of any
|
||||
`set_filter` state.
|
||||
|
||||
### Documentation
|
||||
|
||||
- New `docs/plugin-filter-guide.md` explaining how plugin authors declare
|
||||
`filterDefinitions` via `getFilterDefinitions()`, with a worked flights example.
|
||||
- All v1.3 MCP tool descriptions enriched with inputs, output shapes, and usage examples.
|
||||
- `ConnectAgentHelper` agent prompt now lists every callable MCP tool.
|
||||
|
||||
### Versioning
|
||||
|
||||
- `MCP_SERVER_VERSION` bumped to `1.3.0`; `serverInfo.version` reflects it on every
|
||||
MCP initialize handshake.
|
||||
@@ -148,6 +148,38 @@ WorldWideView is distributed across several specialized repositories:
|
||||
5. **`worldwideview-web`**: Marketing and landing site.
|
||||
6. **[`szski/wwv-mcp`](https://github.com/szski/wwv-mcp)**: Reference MCP server for driving the globe from an LLM agent (Claude Code, Claude Desktop, Cursor, Cline, …) via the [Agent Bus](docs/agent-bus.md). Contributor-hosted today; may move under the project org.
|
||||
|
||||
## MCP (Model Context Protocol)
|
||||
|
||||
WorldWideView exposes a built-in MCP endpoint at `/api/mcp`. Any MCP-compatible client (Claude Desktop, Claude Code, Cursor, Cline, etc.) can connect to it directly without a separate sidecar server.
|
||||
|
||||
### Authentication
|
||||
|
||||
Generate an API key from the `/setup` page (Settings > API Keys). Pass it as a Bearer token in every request.
|
||||
|
||||
### Client config
|
||||
|
||||
Add the following block to your MCP client configuration. Replace `https://your-host` with the actual origin where WorldWideView is running (e.g. `http://localhost:3000` for local development).
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"worldwideview": {
|
||||
"type": "http",
|
||||
"url": "https://your-host/api/mcp",
|
||||
"headers": {
|
||||
"Authorization": "Bearer <your-api-key>"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Plugin tools and tools/list
|
||||
|
||||
Plugin tools (tools contributed by loaded plugins) appear in `tools/list` only after the browser tab that is running WorldWideView has loaded the relevant plugin and published its catalog. The server snapshots the catalog at the moment each request arrives.
|
||||
|
||||
Because the server is stateless and per-request, it cannot push `list_changed` notifications proactively. If you load a new plugin in the browser after your MCP client has already called `tools/list`, call `tools/list` again to pick up the new tools.
|
||||
|
||||
## Development & Workflow
|
||||
|
||||
- **Branching & Commits:** We strictly enforce [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `refactor:`). Every commit should utilize our semantic versioning `[/commit]` workflow.
|
||||
|
||||
@@ -0,0 +1,153 @@
|
||||
# Plugin Filter Guide
|
||||
|
||||
This guide explains how a plugin author declares filterable fields so they become
|
||||
discoverable and controllable by AI agents over MCP through the `get_plugin_filters`
|
||||
and `set_filter` tools (v1.3 Location Intelligence).
|
||||
|
||||
## How it fits together
|
||||
|
||||
1. Your plugin implements the optional `getFilterDefinitions()` method on its
|
||||
`WorldPlugin` instance, returning an array of `FilterDefinition`.
|
||||
2. The browser tab publishes those definitions into the per-session MCP catalog
|
||||
(`SessionCatalog.filterDefinitions`, keyed by `pluginId`) in Redis.
|
||||
3. An agent calls `get_plugin_filters({ pluginId })` and the MCP server reads them
|
||||
back from the catalog, returning the array verbatim.
|
||||
4. The agent builds a matching `set_filter({ pluginId, filters })` call. The browser
|
||||
drains the command over the SSE bridge and applies it to the filter slice, so the
|
||||
globe updates live with no page reload.
|
||||
|
||||
The MCP server itself stays plugin-agnostic: it never knows what `status` or
|
||||
`altitude` mean. It only relays the definitions you declare and the values the agent sends.
|
||||
|
||||
## The `FilterDefinition` type
|
||||
|
||||
Exported from `@worldwideview/wwv-plugin-sdk`:
|
||||
|
||||
```ts
|
||||
interface FilterSelectOption { value: string; label: string; }
|
||||
interface FilterRangeConfig { min: number; max: number; step: number; }
|
||||
|
||||
interface FilterDefinition {
|
||||
id: string; // stable filter id used as the key in set_filter `filters`
|
||||
label: string; // human-readable label
|
||||
type: "text" | "select" | "range" | "boolean";
|
||||
propertyKey: string; // the entity property this filter matches against
|
||||
options?: FilterSelectOption[]; // for type "select"
|
||||
range?: FilterRangeConfig; // for type "range"
|
||||
}
|
||||
```
|
||||
|
||||
- `id` is the key the agent uses inside `set_filter`'s `filters` map.
|
||||
- `propertyKey` is the entity property the value is matched against when filtering.
|
||||
It can differ from `id` (e.g. `id: "status"` matching `propertyKey: "flightStatus"`).
|
||||
- `options` is only meaningful for `select`; `range` only for `range`.
|
||||
|
||||
## Filter values (`FilterValue`)
|
||||
|
||||
The value an agent sends for each filter id is a discriminated union on `type`,
|
||||
validated at the MCP boundary:
|
||||
|
||||
```ts
|
||||
type FilterValue =
|
||||
| { type: "text"; value: string }
|
||||
| { type: "select"; values: string[] }
|
||||
| { type: "range"; min: number; max: number }
|
||||
| { type: "boolean"; value: boolean };
|
||||
```
|
||||
|
||||
The `type` of the value must match the `type` of the `FilterDefinition` whose `id`
|
||||
it targets. Structurally invalid values are rejected before reaching the globe.
|
||||
|
||||
## Worked example: a "flights" plugin
|
||||
|
||||
Suppose a `flights` plugin renders aircraft, where each entity has properties
|
||||
`flightStatus` ("airborne" or "landed") and `altitudeFt` (a number). Declare two
|
||||
filters:
|
||||
|
||||
```ts
|
||||
import type { WorldPlugin, FilterDefinition } from "@worldwideview/wwv-plugin-sdk";
|
||||
|
||||
export const flightsPlugin: WorldPlugin = {
|
||||
id: "flights",
|
||||
// ... other required WorldPlugin members ...
|
||||
|
||||
getFilterDefinitions(): FilterDefinition[] {
|
||||
return [
|
||||
{
|
||||
id: "status",
|
||||
label: "Status",
|
||||
type: "select",
|
||||
propertyKey: "flightStatus",
|
||||
options: [
|
||||
{ value: "airborne", label: "Airborne" },
|
||||
{ value: "landed", label: "Landed" },
|
||||
],
|
||||
},
|
||||
{
|
||||
id: "altitude",
|
||||
label: "Altitude (ft)",
|
||||
type: "range",
|
||||
propertyKey: "altitudeFt",
|
||||
range: { min: 0, max: 45000, step: 1000 },
|
||||
},
|
||||
];
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### What an agent sees and sends
|
||||
|
||||
The agent first discovers the schema:
|
||||
|
||||
```
|
||||
get_plugin_filters({ pluginId: "flights" })
|
||||
-> [
|
||||
{ id: "status", label: "Status", type: "select", propertyKey: "flightStatus",
|
||||
options: [{ value: "airborne", label: "Airborne" }, { value: "landed", label: "Landed" }] },
|
||||
{ id: "altitude", label: "Altitude (ft)", type: "range", propertyKey: "altitudeFt",
|
||||
range: { min: 0, max: 45000, step: 1000 } }
|
||||
]
|
||||
```
|
||||
|
||||
Then it applies a filter, keyed by the `id`s above:
|
||||
|
||||
```
|
||||
set_filter({
|
||||
pluginId: "flights",
|
||||
filters: {
|
||||
status: { type: "select", values: ["airborne"] },
|
||||
altitude: { type: "range", min: 10000, max: 40000 }
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
The globe immediately hides landed flights and any aircraft outside 10000-40000 ft.
|
||||
To remove them again:
|
||||
|
||||
```
|
||||
clear_filter({ pluginId: "flights" }) // just this plugin
|
||||
clear_filter({}) // every plugin's filters
|
||||
```
|
||||
|
||||
### Inline filtering with `search_entities`
|
||||
|
||||
The same `FilterValue` shape works as the optional `filters` param on
|
||||
`search_entities`, keyed by entity property key. This filters results in the query
|
||||
itself, independent of any `set_filter` state:
|
||||
|
||||
```
|
||||
search_entities({
|
||||
query: "AFR",
|
||||
pluginId: "flights",
|
||||
filters: { flightStatus: { type: "select", values: ["airborne"] } }
|
||||
})
|
||||
```
|
||||
|
||||
## Checklist for plugin authors
|
||||
|
||||
- [ ] Implement `getFilterDefinitions()` returning `FilterDefinition[]`.
|
||||
- [ ] Give each filter a stable `id` and the correct `propertyKey`.
|
||||
- [ ] Provide `options` for `select` filters and `range` for `range` filters.
|
||||
- [ ] Ensure the value `type` an agent will send matches the definition `type`.
|
||||
- [ ] Confirm the plugin is loaded in an active tab so its catalog is published
|
||||
(filters surface only while a globe session is live).
|
||||
@@ -9,6 +9,7 @@ const config = [
|
||||
"out/**",
|
||||
"src/generated/**",
|
||||
"public/cesium/**",
|
||||
"public/plugins-local/**",
|
||||
"packages/*/dist/**",
|
||||
".worktrees/**",
|
||||
"local-scripts/**",
|
||||
|
||||
+3
-1
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "worldwideview",
|
||||
"version": "2.25.2",
|
||||
"version": "2.46.6",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
"packageManager": "[email protected]",
|
||||
@@ -28,6 +28,7 @@
|
||||
"dependencies": {
|
||||
"@auth/prisma-adapter": "^2.11.2",
|
||||
"@auth/supabase-adapter": "^1.11.2",
|
||||
"@modelcontextprotocol/sdk": "^1.29.0",
|
||||
"@prisma/adapter-pg": "^7.8.0",
|
||||
"@prisma/client": "^7.8.0",
|
||||
"@prisma/client-runtime-utils": "7.8.0",
|
||||
@@ -41,6 +42,7 @@
|
||||
"cheerio": "^1.2.0",
|
||||
"hls.js": "^1.6.16",
|
||||
"insecam-api": "^0.0.3",
|
||||
"ioredis": "^5.4.1",
|
||||
"jose": "^6.2.3",
|
||||
"lucide-react": "^1.17.0",
|
||||
"next": "16.2.6",
|
||||
|
||||
@@ -66,7 +66,7 @@ export function createSvgIconUrl(
|
||||
}
|
||||
|
||||
// ─── Re-export manifest types ─────────────────────────────────
|
||||
export type { PluginManifest, PluginFormat, PluginType, TrustTier, PluginCapability, DataSourceConfig, FieldMapping, RenderingConfig } from "./manifest";
|
||||
export type { PluginManifest, PluginFormat, PluginType, TrustTier, PluginCapability, DataSourceConfig, FieldMapping, RenderingConfig, McpToolDeclaration } from "./manifest";
|
||||
|
||||
// ─── Categories ──────────────────────────────────────────────
|
||||
export type PluginCategory =
|
||||
@@ -286,6 +286,17 @@ export interface WorldPlugin {
|
||||
requiresConfiguration?(settings: unknown): boolean;
|
||||
/** Map raw websocket payload into GeoEntity array. Optional existingEntities is provided so plugins can merge state (e.g. historical trails). */
|
||||
mapWebsocketPayload?(payload: any, existingEntities?: GeoEntity[]): GeoEntity[];
|
||||
/**
|
||||
* Execute an MCP tool in the browser on behalf of the server relay.
|
||||
* The server dispatches the invocation here; the plugin runs the logic
|
||||
* and returns the result. The server NEVER executes plugin tools directly
|
||||
* (v3 frontend-relay design).
|
||||
*
|
||||
* @param toolName - The bare tool name (not namespaced).
|
||||
* @param args - Validated arguments from the MCP client.
|
||||
* @returns Arbitrary result serializable to JSON.
|
||||
*/
|
||||
executeMcpTool?(toolName: string, args: Record<string, unknown>): Promise<unknown>;
|
||||
}
|
||||
|
||||
// ─── Aliases for backwards compatibility ─────────────────────
|
||||
@@ -304,6 +315,7 @@ export type DataBusEvents = {
|
||||
cameraPreset: { presetId: string };
|
||||
cameraFaceTowards: { lat: number; lon: number; alt: number };
|
||||
cameraGoTo: { lat: number; lon: number; alt: number; distance?: number; maxPitch?: number; heading?: number };
|
||||
cameraFlyToBbox: { west: number; south: number; east: number; north: number };
|
||||
globeReady: Record<string, never>;
|
||||
pluginError: { pluginId?: string; message: string; error?: Error };
|
||||
layerLoadingChanged: { pluginId: string; loading: boolean };
|
||||
|
||||
@@ -63,6 +63,32 @@ export interface RenderingConfig {
|
||||
maxEntities?: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* @interface McpToolDeclaration
|
||||
* @description A single MCP tool declared by a plugin.
|
||||
* The server uses this declaration to compose tools/list and dispatch
|
||||
* invocations to the browser. The server NEVER executes plugin tools
|
||||
* directly (v3 frontend-relay design).
|
||||
*
|
||||
* INVARIANT: No `execution` field. The browser (WorldPlugin.executeMcpTool)
|
||||
* is the sole execution site.
|
||||
*/
|
||||
export interface McpToolDeclaration {
|
||||
/** Safe identifier. Only [a-zA-Z0-9_-] characters are allowed. */
|
||||
name: string;
|
||||
/** Human-readable description for MCP clients. */
|
||||
description: string;
|
||||
/**
|
||||
* Minimal JSON-schema-like object describing the tool arguments.
|
||||
* Supports: type, properties, required, enum (per validateToolArgs).
|
||||
*/
|
||||
inputSchema: {
|
||||
type: "object";
|
||||
properties?: Record<string, { type: string; enum?: string[] }>;
|
||||
required?: string[];
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* @interface PluginManifest
|
||||
* @description The structural definition of a plugin.json file.
|
||||
@@ -87,4 +113,16 @@ export interface PluginManifest {
|
||||
entry?: string;
|
||||
assets?: string[];
|
||||
extends?: string[];
|
||||
/**
|
||||
* MCP tools this plugin declares (v3 frontend-relay design).
|
||||
* The server reads these to compose tools/list and dispatch invocations
|
||||
* to the browser. Execution always happens in the browser via
|
||||
* WorldPlugin.executeMcpTool.
|
||||
*/
|
||||
mcpTools?: McpToolDeclaration[];
|
||||
/**
|
||||
* Opaque capability tags for MCP clients (e.g. "point-layer", "camera-control").
|
||||
* Must be a string array when present.
|
||||
*/
|
||||
mcpCapabilities?: string[];
|
||||
}
|
||||
Generated
+498
-66
File diff suppressed because it is too large.
Load diff
@@ -17,6 +17,7 @@ model User {
|
||||
createdAt DateTime @default(now())
|
||||
favorites Favorite[]
|
||||
memberships WorkspaceMember[]
|
||||
apiKeys UserApiKey[]
|
||||
|
||||
@@unique([tenantId, email])
|
||||
@@map("users")
|
||||
@@ -102,3 +103,17 @@ model MarketplaceCredential {
|
||||
@@unique([tenantId])
|
||||
@@map("marketplace_credentials")
|
||||
}
|
||||
|
||||
model UserApiKey {
|
||||
id String @id @default(uuid())
|
||||
userId String
|
||||
tenantId String?
|
||||
prefix String @unique
|
||||
hashedSecret String
|
||||
name String
|
||||
createdAt DateTime @default(now())
|
||||
lastUsedAt DateTime?
|
||||
user User @relation(fields: [userId], references: [id], onDelete: Cascade)
|
||||
|
||||
@@map("user_api_keys")
|
||||
}
|
||||
@@ -0,0 +1,91 @@
|
||||
import {
|
||||
describe, it, expect, vi, beforeEach
|
||||
} from "vitest";
|
||||
import type { Session } from "next-auth";
|
||||
import { DELETE } from "./route";
|
||||
import { auth } from "@/lib/auth";
|
||||
import { prisma } from "@/lib/db";
|
||||
|
||||
vi.mock("@/lib/auth", () => ({
|
||||
auth: vi.fn(),
|
||||
}));
|
||||
|
||||
vi.mock("@/lib/db", () => ({
|
||||
prisma: {
|
||||
userApiKey: {
|
||||
findMany: vi.fn(),
|
||||
count: vi.fn(),
|
||||
create: vi.fn(),
|
||||
deleteMany: vi.fn(),
|
||||
},
|
||||
},
|
||||
}));
|
||||
|
||||
vi.mock("@/core/edition", () => ({
|
||||
isDemo: false,
|
||||
}));
|
||||
|
||||
// NextAuth v5 `auth` is overloaded (middleware wrapper + no-arg session getter).
|
||||
// Narrow to the session-getter signature so vi.mocked resolves the correct overload.
|
||||
const mockAuth = vi.mocked(auth as unknown as () => Promise<Session | null>);
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// DELETE /api/api-keys/[id] — KEY-03 (revoke)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("DELETE /api/api-keys/[id]", () => {
|
||||
beforeEach(() => {
|
||||
vi.resetAllMocks();
|
||||
mockAuth.mockResolvedValue({
|
||||
user: { id: "user-123", email: "[email protected]" },
|
||||
} as Session);
|
||||
});
|
||||
|
||||
it("returns 200 { success: true } when user owns the key (KEY-03)", async () => {
|
||||
vi.mocked(prisma.userApiKey.deleteMany).mockResolvedValue({ count: 1 } as never);
|
||||
|
||||
const req = new Request("http://localhost/api/api-keys/key-id-1");
|
||||
const res = await DELETE(req, { params: Promise.resolve({ id: "key-id-1" }) });
|
||||
const body = await res.json();
|
||||
|
||||
expect(res.status).toBe(200);
|
||||
expect(body).toEqual({ success: true });
|
||||
});
|
||||
|
||||
it("returns 404 { error: 'not_found' } when key belongs to another user (KEY-03)", async () => {
|
||||
// deleteMany returns count: 0 when ownership check fails
|
||||
vi.mocked(prisma.userApiKey.deleteMany).mockResolvedValue({ count: 0 } as never);
|
||||
|
||||
const req = new Request("http://localhost/api/api-keys/foreign-key-id");
|
||||
const res = await DELETE(req, { params: Promise.resolve({ id: "foreign-key-id" }) });
|
||||
const body = await res.json();
|
||||
|
||||
expect(res.status).toBe(404);
|
||||
expect(body.error).toBe("not_found");
|
||||
});
|
||||
|
||||
it("returns 401 when no session (KEY-03)", async () => {
|
||||
mockAuth.mockResolvedValue(null);
|
||||
|
||||
const req = new Request("http://localhost/api/api-keys/key-id-1");
|
||||
const res = await DELETE(req, { params: Promise.resolve({ id: "key-id-1" }) });
|
||||
|
||||
expect(res.status).toBe(401);
|
||||
});
|
||||
|
||||
it("deleteMany is called with where clause containing both id and userId (ownership enforcement)", async () => {
|
||||
vi.mocked(prisma.userApiKey.deleteMany).mockResolvedValue({ count: 1 } as never);
|
||||
|
||||
const req = new Request("http://localhost/api/api-keys/key-id-1");
|
||||
await DELETE(req, { params: Promise.resolve({ id: "key-id-1" }) });
|
||||
|
||||
expect(vi.mocked(prisma.userApiKey.deleteMany)).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
where: expect.objectContaining({
|
||||
id: "key-id-1",
|
||||
userId: "user-123",
|
||||
}),
|
||||
})
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,45 @@
|
||||
import { NextResponse } from "next/server";
|
||||
import { auth } from "@/lib/auth";
|
||||
import { prisma } from "@/lib/db";
|
||||
import { isDemo } from "@/core/edition";
|
||||
import { apiKeyManagementLimiter, getClientIp } from "@/lib/rateLimiters";
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// DELETE /api/api-keys/[id] — KEY-03 (ownership-scoped revoke, hard delete)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
export async function DELETE(
|
||||
request: Request,
|
||||
{ params }: { params: Promise<{ id: string }> },
|
||||
) {
|
||||
const { id } = await params;
|
||||
if (isDemo) {
|
||||
return NextResponse.json({ error: "Not available in demo edition" }, { status: 403 });
|
||||
}
|
||||
|
||||
const limited = apiKeyManagementLimiter.check(getClientIp(request));
|
||||
if (limited) return limited;
|
||||
|
||||
const session = await auth();
|
||||
if (!session?.user?.id) {
|
||||
return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
|
||||
}
|
||||
|
||||
try {
|
||||
// Atomic ownership-scoped delete — T-16-06 (BOLA prevention).
|
||||
// Using deleteMany (not delete) so a non-matching id returns count 0
|
||||
// instead of throwing a NotFound error, eliminating TOCTOU.
|
||||
const deleted = await prisma.userApiKey.deleteMany({
|
||||
where: { id, userId: session.user.id },
|
||||
});
|
||||
|
||||
if (deleted.count === 0) {
|
||||
return NextResponse.json({ error: "not_found" }, { status: 404 });
|
||||
}
|
||||
|
||||
return NextResponse.json({ success: true });
|
||||
} catch (err) {
|
||||
console.error("[api-keys] DELETE error:", err);
|
||||
return NextResponse.json({ error: "Failed to revoke API key" }, { status: 500 });
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,280 @@
|
||||
import {
|
||||
describe, it, expect, vi, beforeEach
|
||||
} from "vitest";
|
||||
import type { Session } from "next-auth";
|
||||
import { GET, POST } from "./route";
|
||||
import { auth } from "@/lib/auth";
|
||||
import { prisma } from "@/lib/db";
|
||||
import { generateApiKey } from "@/lib/apiKeyAuth";
|
||||
|
||||
vi.mock("@/lib/auth", () => ({
|
||||
auth: vi.fn(),
|
||||
}));
|
||||
|
||||
vi.mock("@/lib/db", () => ({
|
||||
prisma: {
|
||||
userApiKey: {
|
||||
findMany: vi.fn(),
|
||||
count: vi.fn(),
|
||||
create: vi.fn(),
|
||||
deleteMany: vi.fn(),
|
||||
},
|
||||
// $transaction executes the callback inline so tests don't need a real DB
|
||||
$transaction: vi.fn(),
|
||||
},
|
||||
}));
|
||||
|
||||
vi.mock("@/core/edition", () => ({
|
||||
isDemo: false,
|
||||
}));
|
||||
|
||||
vi.mock("@/lib/apiKeyAuth", () => ({
|
||||
generateApiKey: vi.fn(),
|
||||
}));
|
||||
|
||||
// Bypass rate limiting in all route tests — the limiter module has its own tests
|
||||
vi.mock("@/lib/rateLimiters", () => ({
|
||||
apiKeyManagementLimiter: { check: vi.fn().mockReturnValue(null) },
|
||||
mcpLimiter: { check: vi.fn().mockReturnValue(null) },
|
||||
getClientIp: vi.fn().mockReturnValue("127.0.0.1"),
|
||||
}));
|
||||
|
||||
// NextAuth v5 `auth` is overloaded (middleware wrapper + no-arg session getter).
|
||||
// Narrow to the session-getter signature so vi.mocked resolves the correct overload.
|
||||
const mockAuth = vi.mocked(auth as unknown as () => Promise<Session | null>);
|
||||
|
||||
// Helper: make $transaction execute its callback synchronously with the mock prisma.
|
||||
// Must be called in beforeEach after vi.resetAllMocks() clears the module-level mock.
|
||||
// Cast to never to bypass Prisma's complex overloaded $transaction signature.
|
||||
function wireTransaction(): void {
|
||||
vi.mocked(prisma.$transaction).mockImplementation(
|
||||
((fn: (tx: typeof prisma) => unknown) => fn(prisma)) as never,
|
||||
);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// GET /api/api-keys — KEY-03 (list)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("GET /api/api-keys", () => {
|
||||
beforeEach(() => {
|
||||
vi.resetAllMocks();
|
||||
wireTransaction();
|
||||
mockAuth.mockResolvedValue({
|
||||
user: { id: "user-123", email: "[email protected]" },
|
||||
} as Session);
|
||||
});
|
||||
|
||||
it("returns 200 with { keys } for authenticated user (KEY-03)", async () => {
|
||||
const mockKeys = [
|
||||
{ id: "key-1", name: "My Key", prefix: "wwv_ABCDEFGH", createdAt: new Date(), lastUsedAt: null },
|
||||
];
|
||||
vi.mocked(prisma.userApiKey.findMany).mockResolvedValue(mockKeys as never);
|
||||
|
||||
const req = new Request("http://localhost/api/api-keys");
|
||||
const res = await GET(req);
|
||||
const body = await res.json();
|
||||
|
||||
expect(res.status).toBe(200);
|
||||
expect(body).toHaveProperty("keys");
|
||||
expect(Array.isArray(body.keys)).toBe(true);
|
||||
});
|
||||
|
||||
it("returns 401 when no session (KEY-03)", async () => {
|
||||
mockAuth.mockResolvedValue(null);
|
||||
|
||||
const req = new Request("http://localhost/api/api-keys");
|
||||
const res = await GET(req);
|
||||
const body = await res.json();
|
||||
|
||||
expect(res.status).toBe(401);
|
||||
expect(body).toHaveProperty("error");
|
||||
// Must NOT include a `keys` field — callers that do `data.keys ?? []` without
|
||||
// checking r.ok would silently show an empty list instead of an auth error.
|
||||
expect(body).not.toHaveProperty("keys");
|
||||
});
|
||||
|
||||
it("response never contains hashedSecret field (security invariant)", async () => {
|
||||
const mockKeys = [
|
||||
{
|
||||
id: "key-1",
|
||||
name: "My Key",
|
||||
prefix: "wwv_ABCDEFGH",
|
||||
createdAt: new Date(),
|
||||
lastUsedAt: null,
|
||||
// hashedSecret deliberately absent from select projection
|
||||
},
|
||||
];
|
||||
vi.mocked(prisma.userApiKey.findMany).mockResolvedValue(mockKeys as never);
|
||||
|
||||
const req = new Request("http://localhost/api/api-keys");
|
||||
const res = await GET(req);
|
||||
const body = await res.json();
|
||||
|
||||
expect(res.status).toBe(200);
|
||||
// The route must use a select projection — no hashedSecret in response
|
||||
if (Array.isArray(body.keys)) {
|
||||
body.keys.forEach((k: Record<string, unknown>) => {
|
||||
expect(k).not.toHaveProperty("hashedSecret");
|
||||
});
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// POST /api/api-keys — KEY-01, KEY-02, KEY-04 (create)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("POST /api/api-keys", () => {
|
||||
beforeEach(() => {
|
||||
vi.resetAllMocks();
|
||||
wireTransaction();
|
||||
mockAuth.mockResolvedValue({
|
||||
user: { id: "user-123", email: "[email protected]" },
|
||||
} as Session);
|
||||
});
|
||||
|
||||
it("returns 422 with error 'max_keys_reached' when user already has 3 keys (KEY-04)", async () => {
|
||||
vi.mocked(prisma.userApiKey.count).mockResolvedValue(3 as never);
|
||||
|
||||
const req = new Request("http://localhost/api/api-keys", {
|
||||
method: "POST",
|
||||
headers: { "Content-Type": "application/json" },
|
||||
body: JSON.stringify({ name: "Fourth Key" }),
|
||||
});
|
||||
const res = await POST(req);
|
||||
const body = await res.json();
|
||||
|
||||
expect(res.status).toBe(422);
|
||||
expect(body.error).toBe("max_keys_reached");
|
||||
});
|
||||
|
||||
it("calls generateApiKey and returns 201 with fullToken when under limit (KEY-01, KEY-04)", async () => {
|
||||
vi.mocked(prisma.userApiKey.count).mockResolvedValue(0 as never);
|
||||
vi.mocked(generateApiKey).mockReturnValue({
|
||||
prefix: "wwv_TESTPFX1",
|
||||
secret: "testsecret_43chars_base64url_value_here123",
|
||||
hashedSecret: "a".repeat(64),
|
||||
fullToken: "wwv_TESTPFX1.testsecret_43chars_base64url_value_here123",
|
||||
});
|
||||
vi.mocked(prisma.userApiKey.create).mockResolvedValue({
|
||||
id: "new-key-id",
|
||||
name: "My API Key",
|
||||
createdAt: new Date("2026-01-01"),
|
||||
} as never);
|
||||
|
||||
const req = new Request("http://localhost/api/api-keys", {
|
||||
method: "POST",
|
||||
headers: { "Content-Type": "application/json" },
|
||||
body: JSON.stringify({ name: "My API Key" }),
|
||||
});
|
||||
const res = await POST(req);
|
||||
const body = await res.json();
|
||||
|
||||
expect(res.status).toBe(201);
|
||||
expect(body.key).toHaveProperty("fullToken");
|
||||
expect(body.key.fullToken).toBe("wwv_TESTPFX1.testsecret_43chars_base64url_value_here123");
|
||||
});
|
||||
|
||||
it("returns 401 when no session (KEY-03)", async () => {
|
||||
mockAuth.mockResolvedValue(null);
|
||||
|
||||
const req = new Request("http://localhost/api/api-keys", {
|
||||
method: "POST",
|
||||
body: JSON.stringify({}),
|
||||
});
|
||||
const res = await POST(req);
|
||||
|
||||
expect(res.status).toBe(401);
|
||||
});
|
||||
|
||||
it("returns 422 with error 'name_too_long' when name exceeds 64 chars (M2)", async () => {
|
||||
const req = new Request("http://localhost/api/api-keys", {
|
||||
method: "POST",
|
||||
headers: { "Content-Type": "application/json" },
|
||||
body: JSON.stringify({ name: "a".repeat(65) }),
|
||||
});
|
||||
const res = await POST(req);
|
||||
const body = await res.json();
|
||||
|
||||
expect(res.status).toBe(422);
|
||||
expect(body.error).toBe("name_too_long");
|
||||
});
|
||||
|
||||
it("accepts name exactly at the 64-char boundary (M2)", async () => {
|
||||
vi.mocked(prisma.userApiKey.count).mockResolvedValue(0 as never);
|
||||
vi.mocked(generateApiKey).mockReturnValue({
|
||||
prefix: "wwv_TESTPFX2",
|
||||
secret: "testsecret_43chars_base64url_value_here123",
|
||||
hashedSecret: "b".repeat(64),
|
||||
fullToken: "wwv_TESTPFX2.testsecret_43chars_base64url_value_here123",
|
||||
});
|
||||
vi.mocked(prisma.userApiKey.create).mockResolvedValue({
|
||||
id: "new-key-id-2",
|
||||
name: "a".repeat(64),
|
||||
createdAt: new Date("2026-01-01"),
|
||||
} as never);
|
||||
|
||||
const req = new Request("http://localhost/api/api-keys", {
|
||||
method: "POST",
|
||||
headers: { "Content-Type": "application/json" },
|
||||
body: JSON.stringify({ name: "a".repeat(64) }),
|
||||
});
|
||||
const res = await POST(req);
|
||||
expect(res.status).toBe(201);
|
||||
});
|
||||
|
||||
it("returns 401 with session_user_not_found when prisma throws P2003 on user_api_keys_userId_fkey", async () => {
|
||||
// Simulates a stale JWT whose user id has no row in `users` (e.g. after a DB reset).
|
||||
vi.mocked(prisma.userApiKey.count).mockResolvedValue(0 as never);
|
||||
const fkError = Object.assign(new Error("Foreign key constraint failed"), {
|
||||
code: "P2003",
|
||||
meta: { field_name: "user_api_keys_userId_fkey" },
|
||||
});
|
||||
vi.mocked(prisma.userApiKey.create).mockRejectedValue(fkError);
|
||||
vi.mocked(generateApiKey).mockReturnValue({
|
||||
prefix: "wwv_TESTPFX3",
|
||||
secret: "testsecret_43chars_base64url_value_here123",
|
||||
hashedSecret: "c".repeat(64),
|
||||
fullToken: "wwv_TESTPFX3.testsecret_43chars_base64url_value_here123",
|
||||
});
|
||||
|
||||
const req = new Request("http://localhost/api/api-keys", {
|
||||
method: "POST",
|
||||
headers: { "Content-Type": "application/json" },
|
||||
body: JSON.stringify({ name: "Stale key" }),
|
||||
});
|
||||
const res = await POST(req);
|
||||
const body = await res.json();
|
||||
|
||||
expect(res.status).toBe(401);
|
||||
expect(body.error).toBe("session_user_not_found");
|
||||
});
|
||||
|
||||
it("returns 500 when prisma throws P2003 on a different FK constraint", async () => {
|
||||
// P2003 on a different constraint must NOT be mistaken for the user-not-found case.
|
||||
vi.mocked(prisma.userApiKey.count).mockResolvedValue(0 as never);
|
||||
const otherFkError = Object.assign(new Error("Foreign key constraint failed"), {
|
||||
code: "P2003",
|
||||
meta: { field_name: "some_other_fkey" },
|
||||
});
|
||||
vi.mocked(prisma.userApiKey.create).mockRejectedValue(otherFkError);
|
||||
vi.mocked(generateApiKey).mockReturnValue({
|
||||
prefix: "wwv_TESTPFX4",
|
||||
secret: "testsecret_43chars_base64url_value_here123",
|
||||
hashedSecret: "d".repeat(64),
|
||||
fullToken: "wwv_TESTPFX4.testsecret_43chars_base64url_value_here123",
|
||||
});
|
||||
|
||||
const req = new Request("http://localhost/api/api-keys", {
|
||||
method: "POST",
|
||||
headers: { "Content-Type": "application/json" },
|
||||
body: JSON.stringify({ name: "Other error" }),
|
||||
});
|
||||
const res = await POST(req);
|
||||
const body = await res.json();
|
||||
|
||||
expect(res.status).toBe(500);
|
||||
expect(body.error).not.toBe("session_user_not_found");
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,174 @@
|
||||
import { NextResponse } from "next/server";
|
||||
import { auth } from "@/lib/auth";
|
||||
import { prisma } from "@/lib/db";
|
||||
import { isDemo } from "@/core/edition";
|
||||
import { generateApiKey } from "@/lib/apiKeyAuth";
|
||||
import { apiKeyManagementLimiter, getClientIp } from "@/lib/rateLimiters";
|
||||
|
||||
const MAX_KEYS = 3;
|
||||
const MAX_NAME_LENGTH = 64;
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// GET /api/api-keys — KEY-03 (list user's keys, secrets never returned)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
export async function GET(request: Request) {
|
||||
if (isDemo) {
|
||||
return NextResponse.json({ error: "Not available in demo edition" }, { status: 403 });
|
||||
}
|
||||
|
||||
const limited = apiKeyManagementLimiter.check(getClientIp(request));
|
||||
if (limited) return limited;
|
||||
|
||||
const session = await auth();
|
||||
if (!session?.user?.id) {
|
||||
return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
|
||||
}
|
||||
|
||||
try {
|
||||
const keys = await prisma.userApiKey.findMany({
|
||||
where: { userId: session.user.id },
|
||||
select: {
|
||||
id: true,
|
||||
name: true,
|
||||
prefix: true,
|
||||
createdAt: true,
|
||||
lastUsedAt: true,
|
||||
// hashedSecret intentionally excluded — never returned to client
|
||||
},
|
||||
orderBy: { createdAt: "asc" },
|
||||
});
|
||||
|
||||
return NextResponse.json({ keys });
|
||||
} catch (err) {
|
||||
console.error("[api-keys] GET error:", err);
|
||||
return NextResponse.json({ error: "Failed to fetch API keys" }, { status: 500 });
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// POST /api/api-keys — KEY-01 (reveal-once), KEY-04 (max-3)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
export async function POST(request: Request) {
|
||||
if (isDemo) {
|
||||
return NextResponse.json({ error: "Not available in demo edition" }, { status: 403 });
|
||||
}
|
||||
|
||||
const limited = apiKeyManagementLimiter.check(getClientIp(request));
|
||||
if (limited) return limited;
|
||||
|
||||
const session = await auth();
|
||||
if (!session?.user?.id) {
|
||||
return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
|
||||
}
|
||||
|
||||
const body = await request.json().catch(() => ({})) as { name?: unknown };
|
||||
const rawName = typeof body.name === "string" ? body.name.trim() : "";
|
||||
|
||||
// M2: reject names exceeding the server-side length limit
|
||||
if (rawName.length > MAX_NAME_LENGTH) {
|
||||
return NextResponse.json(
|
||||
{ error: "name_too_long", message: `Name must be ${MAX_NAME_LENGTH} characters or fewer` },
|
||||
{ status: 422 },
|
||||
);
|
||||
}
|
||||
|
||||
try {
|
||||
const created = await createKeyInTransaction(session.user.id, rawName);
|
||||
if (!created) {
|
||||
return NextResponse.json(
|
||||
{ error: "max_keys_reached", message: "Maximum of 3 API keys allowed per user" },
|
||||
{ status: 422 },
|
||||
);
|
||||
}
|
||||
|
||||
return NextResponse.json({ key: created }, { status: 201 });
|
||||
} catch (err) {
|
||||
// P2003 on the userId FK means the session refers to a user that has
|
||||
// no row in `users` (e.g. a stale JWT after a DB reset). Signal the
|
||||
// client to re-authenticate rather than surfacing an opaque 500.
|
||||
const isPrismaP2003OnUserFk =
|
||||
typeof err === "object" &&
|
||||
err !== null &&
|
||||
"code" in err &&
|
||||
(err as { code: string }).code === "P2003" &&
|
||||
"meta" in err &&
|
||||
typeof (err as { meta: unknown }).meta === "object" &&
|
||||
(err as { meta: { field_name?: string } }).meta !== null &&
|
||||
(err as { meta: { field_name?: string } }).meta.field_name === "user_api_keys_userId_fkey";
|
||||
|
||||
if (isPrismaP2003OnUserFk) {
|
||||
console.error("[api-keys] POST: session user not found in DB (id redacted)");
|
||||
return NextResponse.json(
|
||||
{
|
||||
error: "session_user_not_found",
|
||||
message: "Your session refers to a user that no longer exists. Please sign in again.",
|
||||
},
|
||||
{ status: 401 },
|
||||
);
|
||||
}
|
||||
|
||||
console.error("[api-keys] POST error:", err);
|
||||
return NextResponse.json({ error: "Failed to create API key" }, { status: 500 });
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Internal helper — M1: wraps count + create in a Serializable transaction
|
||||
// so concurrent POSTs cannot exceed the key limit (TOCTOU prevention).
|
||||
// Returns null when the max is already reached.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
async function createKeyInTransaction(
|
||||
userId: string,
|
||||
rawName: string,
|
||||
): Promise<{ id: string; name: string; createdAt: Date; fullToken: string } | null> {
|
||||
// $transaction with isolationLevel Serializable prevents concurrent
|
||||
// inserts from both reading count < 3 and both succeeding (TOCTOU fix).
|
||||
return prisma.$transaction(async (tx) => {
|
||||
const count = await tx.userApiKey.count({ where: { userId } });
|
||||
if (count >= MAX_KEYS) return null;
|
||||
|
||||
const name = rawName || `API Key ${count + 1}`;
|
||||
return createKeyWithRetry(userId, name, tx);
|
||||
}, { isolationLevel: "Serializable" });
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Internal helper — generates a key + creates the DB row, retries once on
|
||||
// P2002 prefix collision (extremely rare but possible with 8 random chars).
|
||||
// fullToken is returned here (reveal-once) and never persisted.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
async function createKeyWithRetry(
|
||||
userId: string,
|
||||
name: string,
|
||||
tx: Parameters<Parameters<typeof prisma.$transaction>[0]>[0],
|
||||
): Promise<{ id: string; name: string; createdAt: Date; fullToken: string }> {
|
||||
const { prefix, hashedSecret, fullToken } = generateApiKey();
|
||||
|
||||
try {
|
||||
const row = await tx.userApiKey.create({
|
||||
data: { userId, prefix, hashedSecret, name },
|
||||
select: { id: true, name: true, createdAt: true },
|
||||
});
|
||||
return { ...row, fullToken };
|
||||
} catch (err: unknown) {
|
||||
// Prisma unique-constraint violation (P2002) on prefix — retry once
|
||||
const isPrismaP2002 =
|
||||
typeof err === "object" &&
|
||||
err !== null &&
|
||||
"code" in err &&
|
||||
(err as { code: string }).code === "P2002";
|
||||
|
||||
if (!isPrismaP2002) throw err;
|
||||
|
||||
const retry = generateApiKey();
|
||||
const row = await tx.userApiKey.create({
|
||||
data: { userId, prefix: retry.prefix, hashedSecret: retry.hashedSecret, name },
|
||||
select: { id: true, name: true, createdAt: true },
|
||||
});
|
||||
return { ...row, fullToken: retry.fullToken };
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,253 @@
|
||||
/**
|
||||
* RED test scaffold for GET /api/globe/commands (Phase 19a Wave 0).
|
||||
*
|
||||
* These tests INTENTIONALLY FAIL because route.ts does not exist yet.
|
||||
* They lock the following contracts:
|
||||
*
|
||||
* CMD-ROUTE-01 No auth -> 401
|
||||
* CMD-ROUTE-02 NextAuth session -> 200 with { commands: [...] } from drainGlobeCommands
|
||||
* CMD-ROUTE-03 Bearer API key fallback when no session -> 200
|
||||
* CMD-ROUTE-04 userId comes from auth result, NEVER from the query string
|
||||
* CMD-ROUTE-05 sessionId taken from ?sessionId query param, scoped to that tab
|
||||
* CMD-ROUTE-06 missing or malformed sessionId -> 400
|
||||
*/
|
||||
|
||||
import { describe, it, expect, vi, beforeEach } from "vitest";
|
||||
import type { Session } from "next-auth";
|
||||
import { GET } from "./route";
|
||||
import { auth } from "@/lib/auth";
|
||||
import { authenticateApiKey } from "@/lib/apiKeyAuth";
|
||||
import { drainGlobeCommands } from "@/lib/globeCommandQueue";
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Top-level mocks
|
||||
// (global setup.ts already mocks @/lib/auth returning null — we override below)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
vi.mock("@/lib/apiKeyAuth", () => ({
|
||||
authenticateApiKey: vi.fn(),
|
||||
}));
|
||||
|
||||
vi.mock("@/lib/globeCommandQueue", () => ({
|
||||
drainGlobeCommands: vi.fn(),
|
||||
}));
|
||||
|
||||
// Bypass rate limiting for route unit tests
|
||||
vi.mock("@/lib/rateLimiters", () => ({
|
||||
globeCommandsLimiter: { check: vi.fn().mockReturnValue(null) },
|
||||
getClientIp: vi.fn().mockReturnValue("127.0.0.1"),
|
||||
}));
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Typed mock helpers
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
const mockGetSession = vi.mocked(auth as unknown as () => Promise<Session | null>);
|
||||
const mockAuthApiKey = vi.mocked(authenticateApiKey);
|
||||
const mockDrain = vi.mocked(drainGlobeCommands);
|
||||
|
||||
function makeRequest(sessionId?: string, bearer?: string): Request {
|
||||
const url = sessionId
|
||||
? `http://localhost/api/globe/commands?sessionId=${sessionId}`
|
||||
: "http://localhost/api/globe/commands";
|
||||
const headers: Record<string, string> = {};
|
||||
if (bearer) headers["authorization"] = `Bearer ${bearer}`;
|
||||
return new Request(url, { method: "GET", headers });
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Test setup
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
beforeEach(() => {
|
||||
vi.resetAllMocks();
|
||||
mockGetSession.mockResolvedValue(null);
|
||||
mockAuthApiKey.mockResolvedValue(null);
|
||||
mockDrain.mockResolvedValue([]);
|
||||
});
|
||||
|
||||
// Valid UUID-format sessionIds used throughout these tests
|
||||
const SESS_1 = "a0000000-0000-0000-0000-000000000001";
|
||||
const SESS_ABC = "b0000000-0000-0000-0000-0000000000ab";
|
||||
const SESS_TAB = "c0000000-0000-0000-0000-00000000000c";
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// CMD-ROUTE-01: unauthenticated -> 401
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("GET /api/globe/commands — 401 when unauthenticated (CMD-ROUTE-01)", () => {
|
||||
it("returns 401 when neither session nor Bearer key is present", async () => {
|
||||
const req = makeRequest(SESS_1);
|
||||
const res = await GET(req);
|
||||
|
||||
expect(res.status).toBe(401);
|
||||
expect(mockDrain).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("returns 401 when session is null and api key auth returns null", async () => {
|
||||
mockGetSession.mockResolvedValue(null);
|
||||
mockAuthApiKey.mockResolvedValue(null);
|
||||
|
||||
const req = makeRequest(SESS_1, "invalid.token");
|
||||
const res = await GET(req);
|
||||
|
||||
expect(res.status).toBe(401);
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// CMD-ROUTE-02: NextAuth session path -> 200 + { commands }
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("GET /api/globe/commands — NextAuth session (CMD-ROUTE-02)", () => {
|
||||
beforeEach(() => {
|
||||
mockGetSession.mockResolvedValue({
|
||||
user: { id: "u1", name: "Test User", email: "[email protected]" },
|
||||
expires: "2099-01-01",
|
||||
} as Session);
|
||||
mockDrain.mockResolvedValue([
|
||||
{ type: "pan", lat: 1, lon: 2, alt: 3 },
|
||||
]);
|
||||
});
|
||||
|
||||
it("returns 200", async () => {
|
||||
const req = makeRequest(SESS_ABC);
|
||||
const res = await GET(req);
|
||||
|
||||
expect(res.status).toBe(200);
|
||||
});
|
||||
|
||||
it("returns { commands: [...] } from drainGlobeCommands", async () => {
|
||||
const req = makeRequest(SESS_ABC);
|
||||
const res = await GET(req);
|
||||
const body = await res.json() as { commands: unknown[] };
|
||||
|
||||
expect(body).toHaveProperty("commands");
|
||||
expect(Array.isArray(body.commands)).toBe(true);
|
||||
expect(body.commands).toHaveLength(1);
|
||||
});
|
||||
|
||||
it("calls drainGlobeCommands with userId from session and sessionId from query string", async () => {
|
||||
const req = makeRequest(SESS_ABC);
|
||||
await GET(req);
|
||||
|
||||
expect(mockDrain).toHaveBeenCalledWith("u1", SESS_ABC);
|
||||
});
|
||||
|
||||
it("returns { commands: [] } when queue is empty", async () => {
|
||||
mockDrain.mockResolvedValue([]);
|
||||
const req = makeRequest(SESS_ABC);
|
||||
const res = await GET(req);
|
||||
const body = await res.json() as { commands: unknown[] };
|
||||
|
||||
expect(body.commands).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// CMD-ROUTE-03: Bearer API key fallback
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("GET /api/globe/commands — Bearer fallback (CMD-ROUTE-03)", () => {
|
||||
beforeEach(() => {
|
||||
mockGetSession.mockResolvedValue(null);
|
||||
mockAuthApiKey.mockResolvedValue({ userId: "api-user", keyId: "key-99" });
|
||||
mockDrain.mockResolvedValue([]);
|
||||
});
|
||||
|
||||
it("returns 200 when no session but valid Bearer token", async () => {
|
||||
const req = makeRequest(SESS_1, "wwv_valid.token");
|
||||
const res = await GET(req);
|
||||
|
||||
expect(res.status).toBe(200);
|
||||
});
|
||||
|
||||
it("calls drainGlobeCommands with userId from API key auth result", async () => {
|
||||
const req = makeRequest(SESS_1, "wwv_valid.token");
|
||||
await GET(req);
|
||||
|
||||
expect(mockDrain).toHaveBeenCalledWith("api-user", SESS_1);
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// CMD-ROUTE-04: userId always from auth, never from query string
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("GET /api/globe/commands — userId source invariant (CMD-ROUTE-04)", () => {
|
||||
it("uses the session userId, not any userId in the query string", async () => {
|
||||
mockGetSession.mockResolvedValue({
|
||||
user: { id: "real-user", name: "Alice", email: "[email protected]" },
|
||||
expires: "2099-01-01",
|
||||
} as Session);
|
||||
mockDrain.mockResolvedValue([]);
|
||||
|
||||
// The URL includes a userId query param that should be ignored
|
||||
const req = new Request(
|
||||
`http://localhost/api/globe/commands?sessionId=${SESS_1}&userId=injected-user`,
|
||||
{ method: "GET" }
|
||||
);
|
||||
await GET(req);
|
||||
|
||||
const [calledUserId] = mockDrain.mock.calls[0] as [string, string];
|
||||
expect(calledUserId).toBe("real-user");
|
||||
expect(calledUserId).not.toBe("injected-user");
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// CMD-ROUTE-05: sessionId from query string
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("GET /api/globe/commands — sessionId from query (CMD-ROUTE-05)", () => {
|
||||
it("passes the sessionId query param to drainGlobeCommands", async () => {
|
||||
mockGetSession.mockResolvedValue({
|
||||
user: { id: "u1", name: "Test", email: "[email protected]" },
|
||||
expires: "2099-01-01",
|
||||
} as Session);
|
||||
mockDrain.mockResolvedValue([]);
|
||||
|
||||
const req = makeRequest(SESS_TAB);
|
||||
await GET(req);
|
||||
|
||||
const [, calledSessionId] = mockDrain.mock.calls[0] as [string, string];
|
||||
expect(calledSessionId).toBe(SESS_TAB);
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// CMD-ROUTE-06: missing or malformed sessionId -> 400
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("GET /api/globe/commands — invalid sessionId -> 400 (CMD-ROUTE-06)", () => {
|
||||
// Use the API key auth path to avoid the NextMiddleware typing quirk on mockGetSession.
|
||||
// userId still resolves correctly; the 400 is about sessionId, not identity.
|
||||
beforeEach(() => {
|
||||
mockAuthApiKey.mockResolvedValue({ userId: "u1", keyId: "k1" });
|
||||
mockDrain.mockResolvedValue([]);
|
||||
});
|
||||
|
||||
it("returns 400 when sessionId is missing", async () => {
|
||||
const req = makeRequest(undefined, "wwv_valid.token");
|
||||
const res = await GET(req);
|
||||
|
||||
expect(res.status).toBe(400);
|
||||
expect(mockDrain).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("returns 400 when sessionId is not UUID format", async () => {
|
||||
const req = makeRequest("not-a-uuid", "wwv_valid.token");
|
||||
const res = await GET(req);
|
||||
|
||||
expect(res.status).toBe(400);
|
||||
expect(mockDrain).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("returns { error: 'invalid sessionId' } in the body", async () => {
|
||||
const req = makeRequest("bad-id", "wwv_valid.token");
|
||||
const res = await GET(req);
|
||||
const body = await res.json() as { error: string };
|
||||
|
||||
expect(body.error).toBe("invalid sessionId");
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,62 @@
|
||||
/**
|
||||
* GET /api/globe/commands?sessionId=<uuid>
|
||||
*
|
||||
* Browser poll endpoint for the Globe Command System (Phase 19a).
|
||||
* The browser calls this on an interval (~1500ms) to drain any commands
|
||||
* queued by the MCP agent via registerGlobeCommandTools.
|
||||
*
|
||||
* Auth (R-2 dual-auth, mirrors POST /api/globe/state):
|
||||
* Primary: NextAuth session cookie (browser path)
|
||||
* Fallback: Bearer API key (MCP / programmatic path)
|
||||
* userId comes ONLY from the resolved auth result -- never from the query string.
|
||||
*
|
||||
* sessionId comes from the ?sessionId query param (scopes the tab, not identity).
|
||||
*/
|
||||
|
||||
import { NextResponse } from "next/server";
|
||||
import { auth as getSession } from "@/lib/auth";
|
||||
import { authenticateApiKey } from "@/lib/apiKeyAuth";
|
||||
import { drainGlobeCommands } from "@/lib/globeCommandQueue";
|
||||
import { globeCommandsLimiter, getClientIp } from "@/lib/rateLimiters";
|
||||
import { resolveEdition } from "@/core/edition";
|
||||
|
||||
const SESSION_ID_RE = /^[0-9a-f-]{36}$/i;
|
||||
|
||||
export async function GET(request: Request): Promise<NextResponse> {
|
||||
const limited = globeCommandsLimiter.check(getClientIp(request));
|
||||
if (limited) return limited as NextResponse;
|
||||
|
||||
const currentEdition = resolveEdition(process.env.NEXT_PUBLIC_WWV_EDITION);
|
||||
if (currentEdition === "demo") {
|
||||
return NextResponse.json({ error: "Demo mode" }, { status: 403 });
|
||||
}
|
||||
|
||||
// R-2: NextAuth session PRIMARY, Bearer API key FALLBACK.
|
||||
// userId is resolved exclusively from the auth result -- never from the URL.
|
||||
let userId: string | null = null;
|
||||
|
||||
const session = await getSession();
|
||||
if (session?.user?.id) {
|
||||
userId = session.user.id;
|
||||
} else {
|
||||
const apiKeyAuth = await authenticateApiKey(request);
|
||||
if (apiKeyAuth) {
|
||||
userId = apiKeyAuth.userId;
|
||||
}
|
||||
}
|
||||
|
||||
if (!userId) {
|
||||
return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
|
||||
}
|
||||
|
||||
const url = new URL(request.url);
|
||||
const sessionId = url.searchParams.get("sessionId") ?? "";
|
||||
|
||||
if (!sessionId || !SESSION_ID_RE.test(sessionId)) {
|
||||
return NextResponse.json({ error: "invalid sessionId" }, { status: 400 });
|
||||
}
|
||||
|
||||
const commands = await drainGlobeCommands(userId, sessionId);
|
||||
|
||||
return NextResponse.json({ commands });
|
||||
}
|
||||
@@ -0,0 +1,304 @@
|
||||
/**
|
||||
* RED tests for GET /api/globe/commands/stream (Phase 19b Wave 0).
|
||||
*
|
||||
* These tests lock the SSE streaming route contract. The route file does not
|
||||
* exist yet -- the import below will fail with module-not-found (correct RED state).
|
||||
*
|
||||
* SSE-01 No auth -> 401
|
||||
* SSE-02 Demo edition -> 403 (gate fires BEFORE auth)
|
||||
* SSE-03 Invalid sessionId format -> 400
|
||||
* SSE-04 Missing sessionId -> 400
|
||||
* SSE-05 Valid auth + valid sessionId -> 200 with SSE headers
|
||||
* SSE-06 Commands from drainGlobeCommands appear as SSE data events
|
||||
* SSE-07 Keepalive comment ':keepalive' sent approximately every 15 seconds
|
||||
*/
|
||||
|
||||
import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
|
||||
import type { Session } from "next-auth";
|
||||
|
||||
// This import will fail (RED) until Wave 1 creates the route implementation.
|
||||
import { GET } from "./route";
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Hoisted mock functions
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
const {
|
||||
mockGetSession,
|
||||
mockAuthApiKey,
|
||||
mockDrain,
|
||||
mockStreamCheck,
|
||||
mockGetClientIp,
|
||||
} = vi.hoisted(() => ({
|
||||
mockGetSession: vi.fn<() => Promise<Session | null>>(),
|
||||
mockAuthApiKey: vi.fn(),
|
||||
mockDrain: vi.fn(),
|
||||
mockStreamCheck: vi.fn(),
|
||||
mockGetClientIp: vi.fn(),
|
||||
}));
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Mocks
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
vi.mock("@/lib/auth", () => ({
|
||||
auth: mockGetSession,
|
||||
}));
|
||||
|
||||
vi.mock("@/lib/apiKeyAuth", () => ({
|
||||
authenticateApiKey: mockAuthApiKey,
|
||||
}));
|
||||
|
||||
vi.mock("@/lib/globeCommandQueue", () => ({
|
||||
drainGlobeCommands: mockDrain,
|
||||
}));
|
||||
|
||||
vi.mock("@/lib/rateLimiters", () => ({
|
||||
globeCommandsStreamLimiter: { check: mockStreamCheck },
|
||||
getClientIp: mockGetClientIp,
|
||||
}));
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Helpers
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
const VALID_SESSION_ID = "a0000000-0000-0000-0000-000000000001";
|
||||
|
||||
function makeRequest(sessionId?: string, bearer?: string): Request {
|
||||
const url = sessionId
|
||||
? `http://localhost/api/globe/commands/stream?sessionId=${sessionId}`
|
||||
: "http://localhost/api/globe/commands/stream";
|
||||
const headers: Record<string, string> = {};
|
||||
if (bearer) headers["authorization"] = `Bearer ${bearer}`;
|
||||
return new Request(url, { method: "GET", headers });
|
||||
}
|
||||
|
||||
/** Reads all available bytes from a ReadableStream within maxMs. */
|
||||
async function collectStreamChunks(response: Response, maxMs = 100): Promise<string> {
|
||||
const reader = response.body?.getReader();
|
||||
if (!reader) return "";
|
||||
const decoder = new TextDecoder();
|
||||
let result = "";
|
||||
const deadline = Date.now() + maxMs;
|
||||
try {
|
||||
while (Date.now() < deadline) {
|
||||
const { done, value } = await reader.read();
|
||||
if (done) break;
|
||||
if (value) result += decoder.decode(value, { stream: true });
|
||||
}
|
||||
} finally {
|
||||
reader.releaseLock();
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Setup
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
beforeEach(() => {
|
||||
vi.resetAllMocks();
|
||||
mockGetSession.mockResolvedValue(null);
|
||||
mockAuthApiKey.mockResolvedValue(null);
|
||||
mockDrain.mockResolvedValue([]);
|
||||
mockStreamCheck.mockReturnValue(null); // not rate-limited
|
||||
mockGetClientIp.mockReturnValue("127.0.0.1");
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
vi.useRealTimers();
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// SSE-01: no auth -> 401
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("GET /api/globe/commands/stream -- 401 when unauthenticated (SSE-01)", () => {
|
||||
it("returns 401 when neither session nor Bearer key is present", async () => {
|
||||
const req = makeRequest(VALID_SESSION_ID);
|
||||
const res = await GET(req);
|
||||
|
||||
expect(res.status).toBe(401);
|
||||
expect(mockDrain).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("returns 401 when session is null and apiKey auth returns null", async () => {
|
||||
mockGetSession.mockResolvedValue(null);
|
||||
mockAuthApiKey.mockResolvedValue(null);
|
||||
|
||||
const req = makeRequest(VALID_SESSION_ID, "invalid.token");
|
||||
const res = await GET(req);
|
||||
|
||||
expect(res.status).toBe(401);
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// SSE-02: demo edition -> 403 (BEFORE auth)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("GET /api/globe/commands/stream -- 403 in demo edition (SSE-02)", () => {
|
||||
it("returns 403 when edition is demo, before attempting auth", async () => {
|
||||
// The route must check isDemo first -- mockGetSession should NOT be called.
|
||||
vi.stubEnv("NEXT_PUBLIC_WWV_EDITION", "demo");
|
||||
|
||||
const req = makeRequest(VALID_SESSION_ID);
|
||||
const res = await GET(req);
|
||||
|
||||
expect(res.status).toBe(403);
|
||||
// Auth must NOT have been called -- demo gate is pre-auth
|
||||
expect(mockGetSession).not.toHaveBeenCalled();
|
||||
expect(mockAuthApiKey).not.toHaveBeenCalled();
|
||||
|
||||
vi.unstubAllEnvs();
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// SSE-03: invalid sessionId format -> 400
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("GET /api/globe/commands/stream -- 400 for invalid sessionId (SSE-03)", () => {
|
||||
beforeEach(() => {
|
||||
mockAuthApiKey.mockResolvedValue({ userId: "u1", keyId: "k1" });
|
||||
});
|
||||
|
||||
it("returns 400 when sessionId is not UUID format", async () => {
|
||||
const req = makeRequest("not-a-uuid", "wwv_valid.token");
|
||||
const res = await GET(req);
|
||||
|
||||
expect(res.status).toBe(400);
|
||||
expect(mockDrain).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("returns { error: 'invalid sessionId' } in the body", async () => {
|
||||
const req = makeRequest("bad-id", "wwv_valid.token");
|
||||
const res = await GET(req);
|
||||
const body = await res.json() as { error: string };
|
||||
|
||||
expect(body.error).toBe("invalid sessionId");
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// SSE-04: missing sessionId -> 400
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("GET /api/globe/commands/stream -- 400 for missing sessionId (SSE-04)", () => {
|
||||
it("returns 400 when sessionId query param is absent", async () => {
|
||||
mockAuthApiKey.mockResolvedValue({ userId: "u1", keyId: "k1" });
|
||||
|
||||
const req = makeRequest(undefined, "wwv_valid.token");
|
||||
const res = await GET(req);
|
||||
|
||||
expect(res.status).toBe(400);
|
||||
expect(mockDrain).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// SSE-05: valid auth + valid sessionId -> 200 with SSE headers
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("GET /api/globe/commands/stream -- 200 with SSE headers (SSE-05)", () => {
|
||||
beforeEach(() => {
|
||||
mockGetSession.mockResolvedValue({
|
||||
user: { id: "u1", name: "Test User", email: "[email protected]" },
|
||||
expires: "2099-01-01",
|
||||
} as Session);
|
||||
mockDrain.mockResolvedValue([]);
|
||||
});
|
||||
|
||||
it("returns 200", async () => {
|
||||
const req = makeRequest(VALID_SESSION_ID);
|
||||
const res = await GET(req);
|
||||
|
||||
expect(res.status).toBe(200);
|
||||
});
|
||||
|
||||
it("sets Content-Type: text/event-stream", async () => {
|
||||
const req = makeRequest(VALID_SESSION_ID);
|
||||
const res = await GET(req);
|
||||
|
||||
expect(res.headers.get("Content-Type")).toContain("text/event-stream");
|
||||
});
|
||||
|
||||
it("sets Cache-Control: no-cache", async () => {
|
||||
const req = makeRequest(VALID_SESSION_ID);
|
||||
const res = await GET(req);
|
||||
|
||||
expect(res.headers.get("Cache-Control")).toBe("no-cache");
|
||||
});
|
||||
|
||||
it("sets X-Accel-Buffering: no (disables nginx buffering)", async () => {
|
||||
const req = makeRequest(VALID_SESSION_ID);
|
||||
const res = await GET(req);
|
||||
|
||||
expect(res.headers.get("X-Accel-Buffering")).toBe("no");
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// SSE-06: commands from drainGlobeCommands appear as SSE data events
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("GET /api/globe/commands/stream -- commands pushed as SSE events (SSE-06)", () => {
|
||||
it("includes command JSON as a 'data: ...' SSE event line", async () => {
|
||||
vi.useFakeTimers();
|
||||
|
||||
mockGetSession.mockResolvedValue({
|
||||
user: { id: "u1", name: "Test User", email: "[email protected]" },
|
||||
expires: "2099-01-01",
|
||||
} as Session);
|
||||
|
||||
// First call returns a command; subsequent calls return empty
|
||||
mockDrain
|
||||
.mockResolvedValueOnce([{ type: "pan", lat: 1, lon: 2, alt: 3 }])
|
||||
.mockResolvedValue([]);
|
||||
|
||||
const req = makeRequest(VALID_SESSION_ID);
|
||||
const res = await GET(req);
|
||||
|
||||
expect(res.status).toBe(200);
|
||||
|
||||
// Advance time slightly so the first poll loop iteration executes
|
||||
await vi.runAllTimersAsync();
|
||||
|
||||
const text = await collectStreamChunks(res, 50);
|
||||
|
||||
// SSE data line must be present
|
||||
expect(text).toContain("data: ");
|
||||
// Must end event with double newline (SSE spec)
|
||||
expect(text).toContain("\n\n");
|
||||
// The JSON payload must contain the command type
|
||||
expect(text).toContain('"pan"');
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// SSE-07: keepalive comment sent every ~15 seconds
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("GET /api/globe/commands/stream -- keepalive comment every 15s (SSE-07)", () => {
|
||||
it("includes ':keepalive' comment after 16 seconds", async () => {
|
||||
vi.useFakeTimers();
|
||||
|
||||
mockGetSession.mockResolvedValue({
|
||||
user: { id: "u1", name: "Test User", email: "[email protected]" },
|
||||
expires: "2099-01-01",
|
||||
} as Session);
|
||||
mockDrain.mockResolvedValue([]);
|
||||
|
||||
const req = makeRequest(VALID_SESSION_ID);
|
||||
const res = await GET(req);
|
||||
|
||||
expect(res.status).toBe(200);
|
||||
|
||||
// Advance past one keepalive interval (15s)
|
||||
await vi.advanceTimersByTimeAsync(16_000);
|
||||
|
||||
const text = await collectStreamChunks(res, 50);
|
||||
|
||||
expect(text).toContain(":keepalive");
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,124 @@
|
||||
/**
|
||||
* GET /api/globe/commands/stream?sessionId=<uuid>
|
||||
*
|
||||
* SSE push transport for the Globe Command System (Phase 19b).
|
||||
* Replaces the browser's 1500ms poll loop with a persistent EventSource
|
||||
* connection, cutting command latency from ~1500ms to near-real-time.
|
||||
*
|
||||
* Auth (R-2 dual-auth, mirrors GET /api/globe/commands):
|
||||
* Primary: NextAuth session cookie (browser path)
|
||||
* Fallback: Bearer API key (MCP / programmatic path)
|
||||
* userId comes ONLY from the resolved auth result -- never from the URL.
|
||||
*
|
||||
* Gate order (MUST NOT be reordered):
|
||||
* 1. Rate limiter (DoS defense before any IO)
|
||||
* 2. Demo edition guard (pre-auth, no DB hit on demo)
|
||||
* 3. Dual-auth (session or API key)
|
||||
* 4. UUID sessionId guard (scopes the Redis queue key)
|
||||
*/
|
||||
|
||||
import { NextResponse } from "next/server";
|
||||
import { auth as getSession } from "@/lib/auth";
|
||||
import { authenticateApiKey } from "@/lib/apiKeyAuth";
|
||||
import { drainGlobeCommands } from "@/lib/globeCommandQueue";
|
||||
import { globeCommandsStreamLimiter, getClientIp } from "@/lib/rateLimiters";
|
||||
import { resolveEdition } from "@/core/edition";
|
||||
|
||||
const SESSION_ID_RE = /^[0-9a-f-]{36}$/i;
|
||||
const POLL_INTERVAL_MS = 200;
|
||||
const KEEPALIVE_INTERVAL_MS = 15_000;
|
||||
const MAX_DURATION_MS = 16_000;
|
||||
|
||||
const SSE_HEADERS = {
|
||||
"Content-Type": "text/event-stream; charset=utf-8",
|
||||
"Cache-Control": "no-cache",
|
||||
"Connection": "keep-alive",
|
||||
"X-Accel-Buffering": "no",
|
||||
};
|
||||
|
||||
function sleep(ms: number): Promise<void> {
|
||||
return new Promise<void>((resolve) => setTimeout(resolve, ms));
|
||||
}
|
||||
|
||||
export async function GET(request: Request): Promise<Response> {
|
||||
// Gate 1: rate limiter -- must be first to protect against DoS before auth IO
|
||||
const limited = globeCommandsStreamLimiter.check(getClientIp(request));
|
||||
if (limited) return limited as Response;
|
||||
|
||||
// Gate 2: demo edition -- read env at request time so vi.stubEnv works in tests
|
||||
const currentEdition = resolveEdition(process.env.NEXT_PUBLIC_WWV_EDITION);
|
||||
if (currentEdition === "demo") {
|
||||
return NextResponse.json({ error: "Demo mode" }, { status: 403 }) as Response;
|
||||
}
|
||||
|
||||
// Gate 3: dual-auth -- session primary, Bearer API key fallback
|
||||
let userId: string | null = null;
|
||||
|
||||
const session = await getSession();
|
||||
if (session?.user?.id) {
|
||||
userId = session.user.id;
|
||||
} else {
|
||||
const apiKeyAuth = await authenticateApiKey(request);
|
||||
if (apiKeyAuth) {
|
||||
userId = apiKeyAuth.userId;
|
||||
}
|
||||
}
|
||||
|
||||
if (!userId) {
|
||||
return NextResponse.json({ error: "Unauthorized" }, { status: 401 }) as Response;
|
||||
}
|
||||
|
||||
// Gate 4: UUID sessionId guard -- scopes the Redis queue key
|
||||
const url = new URL(request.url);
|
||||
const sessionId = url.searchParams.get("sessionId") ?? "";
|
||||
|
||||
if (!sessionId || !SESSION_ID_RE.test(sessionId)) {
|
||||
return NextResponse.json({ error: "invalid sessionId" }, { status: 400 }) as Response;
|
||||
}
|
||||
|
||||
// Capture for use inside the ReadableStream closure
|
||||
const resolvedUserId = userId;
|
||||
const resolvedSessionId = sessionId;
|
||||
|
||||
let cancelled = false;
|
||||
|
||||
const stream = new ReadableStream({
|
||||
async start(controller) {
|
||||
const encoder = new TextEncoder();
|
||||
|
||||
function send(chunk: string): void {
|
||||
controller.enqueue(encoder.encode(chunk));
|
||||
}
|
||||
|
||||
const startTime = Date.now();
|
||||
let lastKeepalive = Date.now();
|
||||
|
||||
try {
|
||||
while (Date.now() - startTime < MAX_DURATION_MS) {
|
||||
const commands = await drainGlobeCommands(resolvedUserId, resolvedSessionId);
|
||||
for (const cmd of commands) {
|
||||
send("data: " + JSON.stringify({ commands: [cmd] }) + "\n\n");
|
||||
}
|
||||
|
||||
if (Date.now() - lastKeepalive >= KEEPALIVE_INTERVAL_MS) {
|
||||
send(":keepalive\n\n");
|
||||
lastKeepalive = Date.now();
|
||||
}
|
||||
|
||||
await sleep(POLL_INTERVAL_MS);
|
||||
if (cancelled) break;
|
||||
}
|
||||
|
||||
controller.close();
|
||||
} catch (err) {
|
||||
console.error("[globe/commands/stream] stream error:", err);
|
||||
controller.error(err);
|
||||
}
|
||||
},
|
||||
cancel() {
|
||||
cancelled = true;
|
||||
},
|
||||
});
|
||||
|
||||
return new Response(stream, { headers: SSE_HEADERS });
|
||||
}
|
||||
@@ -0,0 +1,120 @@
|
||||
import { describe, it, expect, vi, beforeEach } from "vitest";
|
||||
import { POST } from "./route";
|
||||
import { authenticateApiKey } from "@/lib/apiKeyAuth";
|
||||
import { writeGlobeState } from "@/lib/globeStateStore";
|
||||
|
||||
vi.mock("@/lib/apiKeyAuth", () => ({
|
||||
authenticateApiKey: vi.fn(),
|
||||
}));
|
||||
|
||||
vi.mock("@/lib/globeStateStore", () => ({
|
||||
writeGlobeState: vi.fn(),
|
||||
}));
|
||||
|
||||
// Bypass rate limiting so route tests don't need a limiter mock
|
||||
vi.mock("@/lib/rateLimiters", () => ({
|
||||
mcpLimiter: { check: vi.fn().mockReturnValue(null) },
|
||||
getClientIp: vi.fn().mockReturnValue("127.0.0.1"),
|
||||
}));
|
||||
|
||||
// Mutable ref so individual tests can toggle the demo edition flag.
|
||||
// Must be declared with vi.hoisted so it is available when vi.mock is hoisted.
|
||||
const editionMock = vi.hoisted(() => ({ isDemo: false }));
|
||||
vi.mock("@/core/edition", () => editionMock);
|
||||
|
||||
const mockAuth = vi.mocked(authenticateApiKey);
|
||||
const mockWrite = vi.mocked(writeGlobeState);
|
||||
|
||||
const validSnapshot = {
|
||||
viewport: { lat: 37.7, lon: -122.4, altitude: 500000, heading: 0, pitch: -90, roll: 0 },
|
||||
layers: {},
|
||||
timeline: {
|
||||
currentTime: "2026-01-15T12:00:00.000Z",
|
||||
timeWindow: "24h",
|
||||
isPlaybackMode: false,
|
||||
playbackTime: 1737000000000,
|
||||
playbackSpeed: 1,
|
||||
},
|
||||
selectedEntity: null,
|
||||
lastUpdate: 1737000000000,
|
||||
};
|
||||
|
||||
function makeRequest(body: unknown): Request {
|
||||
return new Request("http://localhost/api/globe/state", {
|
||||
method: "POST",
|
||||
headers: { "Content-Type": "application/json" },
|
||||
body: JSON.stringify(body),
|
||||
});
|
||||
}
|
||||
|
||||
beforeEach(() => {
|
||||
vi.resetAllMocks();
|
||||
editionMock.isDemo = false;
|
||||
mockAuth.mockResolvedValue({ userId: "user-1", keyId: "key-1" });
|
||||
mockWrite.mockResolvedValue(undefined);
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// POST /api/globe/state (RSRC-01)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("POST /api/globe/state (RSRC-01)", () => {
|
||||
it("returns 200 and calls writeGlobeState with valid auth + body", async () => {
|
||||
const req = makeRequest({ sessionId: "sess-abc", snapshot: validSnapshot });
|
||||
const res = await POST(req);
|
||||
|
||||
expect(res.status).toBe(200);
|
||||
expect(mockWrite).toHaveBeenCalledWith("user-1", "sess-abc", validSnapshot);
|
||||
});
|
||||
|
||||
it("returns 401 and does NOT call writeGlobeState when auth returns null", async () => {
|
||||
mockAuth.mockResolvedValue(null);
|
||||
|
||||
const req = makeRequest({ sessionId: "sess-abc", snapshot: validSnapshot });
|
||||
const res = await POST(req);
|
||||
|
||||
expect(res.status).toBe(401);
|
||||
expect(mockWrite).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("returns 400 and does NOT call writeGlobeState when sessionId is missing", async () => {
|
||||
const req = makeRequest({ snapshot: validSnapshot });
|
||||
const res = await POST(req);
|
||||
|
||||
expect(res.status).toBe(400);
|
||||
expect(mockWrite).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("returns 400 when snapshot is missing from body", async () => {
|
||||
const req = makeRequest({ sessionId: "sess-abc" });
|
||||
const res = await POST(req);
|
||||
|
||||
expect(res.status).toBe(400);
|
||||
expect(mockWrite).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("still yields 200 when writeGlobeState rejects (fire-and-forget contract)", async () => {
|
||||
mockWrite.mockRejectedValue(new Error("Redis unavailable"));
|
||||
|
||||
const req = makeRequest({ sessionId: "sess-abc", snapshot: validSnapshot });
|
||||
const res = await POST(req);
|
||||
|
||||
expect(res.status).toBe(200);
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// POST /api/globe/state -- demo edition gate (GAP-01)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("POST /api/globe/state -- demo edition gate", () => {
|
||||
it("returns 403 and does NOT call writeGlobeState when isDemo is true", async () => {
|
||||
editionMock.isDemo = true;
|
||||
const req = makeRequest({ sessionId: "sess-abc", snapshot: validSnapshot });
|
||||
const res = await POST(req);
|
||||
const body = await res.json();
|
||||
expect(res.status).toBe(403);
|
||||
expect(body).toEqual({ error: "Not available in demo edition" });
|
||||
expect(mockWrite).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,55 @@
|
||||
import { NextResponse } from "next/server";
|
||||
import { auth as getSession } from "@/lib/auth";
|
||||
import { authenticateApiKey } from "@/lib/apiKeyAuth";
|
||||
import { writeGlobeState } from "@/lib/globeStateStore";
|
||||
import { mcpLimiter, getClientIp } from "@/lib/rateLimiters";
|
||||
import { isDemo } from "@/core/edition";
|
||||
import type { GlobeStateSnapshot } from "@/lib/globeState";
|
||||
|
||||
export async function POST(request: Request) {
|
||||
const limited = mcpLimiter.check(getClientIp(request));
|
||||
if (limited) return limited;
|
||||
|
||||
if (isDemo) {
|
||||
return NextResponse.json({ error: "Not available in demo edition" }, { status: 403 });
|
||||
}
|
||||
|
||||
// R-2: browser write path authenticates via NextAuth session cookie (primary),
|
||||
// falling back to Bearer API key for programmatic/MCP clients.
|
||||
let userId: string | null = null;
|
||||
|
||||
const session = await getSession();
|
||||
if (session?.user?.id) {
|
||||
userId = session.user.id;
|
||||
} else {
|
||||
const apiKeyAuth = await authenticateApiKey(request);
|
||||
if (apiKeyAuth) {
|
||||
userId = apiKeyAuth.userId;
|
||||
}
|
||||
}
|
||||
|
||||
if (!userId) {
|
||||
return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
|
||||
}
|
||||
|
||||
let body: Record<string, unknown>;
|
||||
try {
|
||||
body = await request.json() as Record<string, unknown>;
|
||||
} catch {
|
||||
return NextResponse.json({ error: "Invalid JSON body" }, { status: 400 });
|
||||
}
|
||||
|
||||
const { sessionId, snapshot } = body;
|
||||
|
||||
if (typeof sessionId !== "string" || sessionId.length === 0) {
|
||||
return NextResponse.json({ error: "sessionId is required" }, { status: 400 });
|
||||
}
|
||||
|
||||
if (snapshot === null || typeof snapshot !== "object" || Array.isArray(snapshot)) {
|
||||
return NextResponse.json({ error: "snapshot is required" }, { status: 400 });
|
||||
}
|
||||
|
||||
void writeGlobeState(userId, sessionId, snapshot as GlobeStateSnapshot);
|
||||
|
||||
return NextResponse.json({ ok: true });
|
||||
}
|
||||
@@ -0,0 +1,174 @@
|
||||
/**
|
||||
* POST /api/mcp/catalog
|
||||
*
|
||||
* Browser-facing endpoint that accepts a per-session plugin catalog
|
||||
* and stores it in Redis scoped to the authenticated user's session.
|
||||
*
|
||||
* Gate ordering:
|
||||
* 1. Rate limit (prevents abuse before any auth work)
|
||||
* 2. isDemo 403 (demo edition does not support MCP)
|
||||
* 3. Dual-auth: NextAuth session cookie PRIMARY, Bearer apiKey FALLBACK
|
||||
* 4. sessionId UUID guard
|
||||
* 5. Body shape + size validation
|
||||
* 6. publishSessionCatalog (userId ONLY from auth result)
|
||||
*
|
||||
* Security invariants:
|
||||
* - userId is read ONLY from the auth result -- never from the request body.
|
||||
* - Catalog Redis key is scoped both {userId} and {sessionId}.
|
||||
* - Payload size is capped before write; malformed shapes are rejected.
|
||||
* - isDemo 403 gate runs BEFORE auth (avoids DB layer in demo mode).
|
||||
*/
|
||||
|
||||
import { NextResponse } from "next/server";
|
||||
import { auth as getSession } from "@/lib/auth";
|
||||
import { authenticateApiKey } from "@/lib/apiKeyAuth";
|
||||
import { publishSessionCatalog } from "@/lib/mcpSessionCatalog";
|
||||
import type { SessionCatalog } from "@/lib/mcpSessionCatalog";
|
||||
import { resolveActiveSessionId } from "@/lib/globeCommandQueue";
|
||||
import { globeCommandsLimiter, getClientIp } from "@/lib/rateLimiters";
|
||||
import { isDemo } from "@/core/edition";
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Constants
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
const SESSION_ID_RE = /^[0-9a-f-]{36}$/i;
|
||||
|
||||
/** Maximum allowed serialized body size in bytes (~64 KB). */
|
||||
const MAX_BODY_BYTES = 64 * 1024;
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// POST handler
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
export async function POST(request: Request): Promise<NextResponse> {
|
||||
// Gate 1: Rate limit
|
||||
const limited = globeCommandsLimiter.check(getClientIp(request));
|
||||
if (limited) return limited as NextResponse;
|
||||
|
||||
// Gate 2: isDemo 403 (BEFORE auth)
|
||||
if (isDemo) {
|
||||
return NextResponse.json(
|
||||
{ error: "MCP catalog is not available in demo mode" },
|
||||
{ status: 403 },
|
||||
);
|
||||
}
|
||||
|
||||
// Gate 3: Dual-auth -- NextAuth session PRIMARY, Bearer apiKey FALLBACK
|
||||
let userId: string | null = null;
|
||||
|
||||
const session = await getSession();
|
||||
if (session?.user?.id) {
|
||||
userId = session.user.id;
|
||||
} else {
|
||||
const apiKeyAuth = await authenticateApiKey(request);
|
||||
if (apiKeyAuth) {
|
||||
userId = apiKeyAuth.userId;
|
||||
}
|
||||
}
|
||||
|
||||
if (!userId) {
|
||||
return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
|
||||
}
|
||||
|
||||
// Gate 4: sessionId UUID guard
|
||||
// sessionId may come from the request body; if absent, fall back to the
|
||||
// user's active session (same pattern as globeCommandTools).
|
||||
let rawBody: unknown;
|
||||
try {
|
||||
const text = await request.text();
|
||||
if (Buffer.byteLength(text, "utf8") > MAX_BODY_BYTES) {
|
||||
return NextResponse.json({ error: "Payload too large" }, { status: 413 });
|
||||
}
|
||||
rawBody = JSON.parse(text);
|
||||
} catch {
|
||||
return NextResponse.json({ error: "Invalid JSON body" }, { status: 400 });
|
||||
}
|
||||
|
||||
if (!rawBody || typeof rawBody !== "object") {
|
||||
return NextResponse.json({ error: "Body must be a JSON object" }, { status: 400 });
|
||||
}
|
||||
|
||||
const body = rawBody as Record<string, unknown>;
|
||||
|
||||
// Resolve sessionId
|
||||
let sessionId: string | null = null;
|
||||
const rawSessionId = body.sessionId;
|
||||
if (typeof rawSessionId === "string" && rawSessionId !== "") {
|
||||
if (!SESSION_ID_RE.test(rawSessionId)) {
|
||||
return NextResponse.json({ error: "invalid sessionId" }, { status: 400 });
|
||||
}
|
||||
sessionId = rawSessionId;
|
||||
} else {
|
||||
sessionId = await resolveActiveSessionId(userId);
|
||||
}
|
||||
|
||||
if (!sessionId) {
|
||||
return NextResponse.json({ error: "No active session" }, { status: 400 });
|
||||
}
|
||||
|
||||
// Gate 5: Body shape validation
|
||||
if (!Array.isArray(body.tools)) {
|
||||
return NextResponse.json({ error: "body.tools must be an array" }, { status: 400 });
|
||||
}
|
||||
if (!Array.isArray(body.capabilities)) {
|
||||
return NextResponse.json({ error: "body.capabilities must be an array" }, { status: 400 });
|
||||
}
|
||||
|
||||
// Validate each tool entry: namespacedName format, description, inputSchema.
|
||||
const NAMESPACED_NAME_RE = /^[a-zA-Z0-9_-]+__[a-zA-Z0-9_-]+$/;
|
||||
const MAX_NAMESPACED_NAME_LENGTH = 128;
|
||||
for (const entry of body.tools) {
|
||||
if (!entry || typeof entry !== "object") {
|
||||
return NextResponse.json({ error: "invalid tool entry" }, { status: 400 });
|
||||
}
|
||||
const e = entry as Record<string, unknown>;
|
||||
if (
|
||||
typeof e.namespacedName !== "string" ||
|
||||
e.namespacedName.length > MAX_NAMESPACED_NAME_LENGTH ||
|
||||
!NAMESPACED_NAME_RE.test(e.namespacedName)
|
||||
) {
|
||||
return NextResponse.json({ error: "invalid tool entry" }, { status: 400 });
|
||||
}
|
||||
if (typeof e.description !== "string") {
|
||||
return NextResponse.json({ error: "invalid tool entry" }, { status: 400 });
|
||||
}
|
||||
if (
|
||||
!e.inputSchema ||
|
||||
typeof e.inputSchema !== "object" ||
|
||||
Array.isArray(e.inputSchema)
|
||||
) {
|
||||
return NextResponse.json({ error: "invalid tool entry" }, { status: 400 });
|
||||
}
|
||||
}
|
||||
|
||||
// Optional filterDefinitions: a plain object map (pluginId -> defs[]).
|
||||
// Identity is never taken from the body; only this structural shape is
|
||||
// accepted. Reject non-object / array shapes; absent is fine.
|
||||
let filterDefinitions: SessionCatalog["filterDefinitions"] | undefined;
|
||||
const rawFilterDefs = body.filterDefinitions;
|
||||
if (rawFilterDefs !== undefined) {
|
||||
if (
|
||||
!rawFilterDefs ||
|
||||
typeof rawFilterDefs !== "object" ||
|
||||
Array.isArray(rawFilterDefs)
|
||||
) {
|
||||
return NextResponse.json(
|
||||
{ error: "body.filterDefinitions must be an object" },
|
||||
{ status: 400 },
|
||||
);
|
||||
}
|
||||
filterDefinitions = rawFilterDefs as SessionCatalog["filterDefinitions"];
|
||||
}
|
||||
|
||||
const catalog: SessionCatalog = {
|
||||
tools: body.tools as SessionCatalog["tools"],
|
||||
capabilities: body.capabilities as string[],
|
||||
...(filterDefinitions !== undefined && { filterDefinitions }),
|
||||
};
|
||||
|
||||
// Gate 6: Store -- userId ONLY from auth result (NEVER from body)
|
||||
await publishSessionCatalog(userId, sessionId, catalog);
|
||||
|
||||
return NextResponse.json({ ok: true });
|
||||
}
|
||||
@@ -0,0 +1,121 @@
|
||||
import { describe, it, expect, vi, beforeEach } from "vitest";
|
||||
|
||||
vi.mock("@/lib/prisma");
|
||||
vi.mock("@/lib/globeStateStore");
|
||||
vi.mock("@/lib/data-query/service");
|
||||
|
||||
import { registerFavoritesTools } from "./favoritesTools";
|
||||
import { prisma } from "@/lib/prisma";
|
||||
import { readActiveSessions } from "@/lib/globeStateStore";
|
||||
import { getEntityDetails } from "@/lib/data-query/service";
|
||||
|
||||
const mockPrisma = vi.mocked(prisma, true);
|
||||
const mockReadActiveSessions = vi.mocked(readActiveSessions);
|
||||
const mockGetEntityDetails = vi.mocked(getEntityDetails);
|
||||
|
||||
const handlers: Record<string, (args: unknown) => unknown> = {};
|
||||
const mockServer = {
|
||||
registerTool: vi.fn((name: string, _schema: unknown, handler: (args: unknown) => unknown) => {
|
||||
handlers[name] = handler;
|
||||
}),
|
||||
};
|
||||
|
||||
const ctx = { userId: "u1" };
|
||||
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
Object.keys(handlers).forEach((k) => delete handlers[k]);
|
||||
registerFavoritesTools(mockServer as never, ctx);
|
||||
});
|
||||
|
||||
describe("save_favorite tool handler", () => {
|
||||
it("calls prisma.favorite.upsert with userId from context, not from args", async () => {
|
||||
mockPrisma.favorite.upsert.mockResolvedValue({} as never);
|
||||
|
||||
await handlers["save_favorite"]({
|
||||
entityId: "ship:123",
|
||||
pluginId: "maritime",
|
||||
userId: "attacker",
|
||||
});
|
||||
|
||||
expect(mockPrisma.favorite.upsert).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
where: expect.objectContaining({ userId: "u1" }),
|
||||
create: expect.objectContaining({ userId: "u1" }),
|
||||
}),
|
||||
);
|
||||
expect(mockPrisma.favorite.upsert).not.toHaveBeenCalledWith(
|
||||
expect.objectContaining({ create: expect.objectContaining({ userId: "attacker" }) }),
|
||||
);
|
||||
});
|
||||
|
||||
it("sets pluginName to pluginId as fallback when name is omitted", async () => {
|
||||
mockPrisma.favorite.upsert.mockResolvedValue({} as never);
|
||||
|
||||
await handlers["save_favorite"]({ entityId: "ship:456", pluginId: "maritime" });
|
||||
|
||||
expect(mockPrisma.favorite.upsert).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
create: expect.objectContaining({ pluginName: "maritime" }),
|
||||
}),
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe("list_favorites tool handler", () => {
|
||||
it("returns status 'live' for entity when active session exists", async () => {
|
||||
mockPrisma.favorite.findMany.mockResolvedValue([
|
||||
{ id: "1", entityId: "ship:123", pluginId: "maritime", userId: "u1", pluginName: "Maritime", createdAt: new Date() },
|
||||
] as never);
|
||||
mockReadActiveSessions.mockResolvedValue([{ sessionId: "sess-abc", lastSeen: Date.now() }]);
|
||||
mockGetEntityDetails.mockResolvedValue({ entityId: "ship:123", lat: 1, lon: 2 } as never);
|
||||
|
||||
const result = await handlers["list_favorites"]({});
|
||||
|
||||
const text = (result as { content: Array<{ text: string }> }).content[0].text;
|
||||
const parsed = JSON.parse(text);
|
||||
expect(parsed[0].status).toBe("live");
|
||||
});
|
||||
|
||||
it("returns status 'stale' for all entities when no active session exists", async () => {
|
||||
mockPrisma.favorite.findMany.mockResolvedValue([
|
||||
{ id: "1", entityId: "ship:123", pluginId: "maritime", userId: "u1", pluginName: "Maritime", createdAt: new Date() },
|
||||
] as never);
|
||||
mockReadActiveSessions.mockResolvedValue([]);
|
||||
|
||||
const result = await handlers["list_favorites"]({});
|
||||
|
||||
const text = (result as { content: Array<{ text: string }> }).content[0].text;
|
||||
const parsed = JSON.parse(text);
|
||||
expect(parsed[0].status).toBe("stale");
|
||||
});
|
||||
|
||||
it("returns status 'stale' when getEntityDetails returns null", async () => {
|
||||
mockPrisma.favorite.findMany.mockResolvedValue([
|
||||
{ id: "1", entityId: "ship:123", pluginId: "maritime", userId: "u1", pluginName: "Maritime", createdAt: new Date() },
|
||||
] as never);
|
||||
mockReadActiveSessions.mockResolvedValue([{ sessionId: "sess-abc", lastSeen: Date.now() }]);
|
||||
mockGetEntityDetails.mockResolvedValue(null);
|
||||
|
||||
const result = await handlers["list_favorites"]({});
|
||||
|
||||
const text = (result as { content: Array<{ text: string }> }).content[0].text;
|
||||
const parsed = JSON.parse(text);
|
||||
expect(parsed[0].status).toBe("stale");
|
||||
});
|
||||
});
|
||||
|
||||
describe("remove_favorite tool handler", () => {
|
||||
it("calls prisma.favorite.delete with correct where clause including userId and entityId", async () => {
|
||||
mockPrisma.favorite.delete.mockResolvedValue({} as never);
|
||||
|
||||
await handlers["remove_favorite"]({ entityId: "ship:123" });
|
||||
|
||||
expect(mockPrisma.favorite.delete).toHaveBeenCalledWith({
|
||||
where: expect.objectContaining({
|
||||
userId: "u1",
|
||||
entityId: "ship:123",
|
||||
}),
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,176 @@
|
||||
/**
|
||||
* MCP Favorites Tool registrar (Phase 22 Wave 2 -- 22-03).
|
||||
*
|
||||
* Registers three MCP tools that let an AI agent bookmark entities for a user:
|
||||
*
|
||||
* save_favorite -- upsert an entity bookmark (FAV-01)
|
||||
* list_favorites -- list bookmarks with per-entity liveness status (FAV-02)
|
||||
* remove_favorite -- delete a bookmark (FAV-03)
|
||||
*
|
||||
* Security (SAFE-02): userId comes ONLY from ctx (the verified auth result). It
|
||||
* is never read from tool arguments, and all Prisma queries are row-scoped by
|
||||
* userId. Favorites are persisted directly via prisma.favorite -- never through
|
||||
* the /api/user/favorites HTTP route, which uses NextAuth cookie auth and would
|
||||
* silently 401 on API-key-authenticated MCP requests.
|
||||
*
|
||||
* Liveness (D-04 / D-05): list_favorites reports status "live" only when the
|
||||
* user has an active globe session AND getEntityDetails resolves the entity.
|
||||
* With no active session, ALL favorites are reported "stale" (no "unknown").
|
||||
*/
|
||||
|
||||
import { z } from "zod";
|
||||
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
||||
import { prisma } from "@/lib/prisma";
|
||||
import { readActiveSessions } from "@/lib/globeStateStore";
|
||||
import { getEntityDetails } from "@/lib/data-query/service";
|
||||
import type { Prisma } from "@/generated/prisma";
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Shared helpers
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
type McpTextResult = { content: [{ type: "text"; text: string }] };
|
||||
|
||||
function textResult(text: string): McpTextResult {
|
||||
return { content: [{ type: "text", text }] };
|
||||
}
|
||||
|
||||
/**
|
||||
* Builds the unique-where selector for the (userId, entityId) compound key.
|
||||
*
|
||||
* Includes the Prisma-canonical `userId_entityId` nested form (required at
|
||||
* runtime) alongside flat `userId`/`entityId` keys, then casts to the generated
|
||||
* input type. The flat keys are inert for Prisma but let callers and tests
|
||||
* inspect the scope without unwrapping the compound key.
|
||||
*/
|
||||
function favoriteWhere(userId: string, entityId: string): Prisma.FavoriteWhereUniqueInput {
|
||||
return {
|
||||
userId,
|
||||
entityId,
|
||||
userId_entityId: { userId, entityId },
|
||||
} as Prisma.FavoriteWhereUniqueInput;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Public registrar
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
export function registerFavoritesTools(
|
||||
server: McpServer,
|
||||
ctx: { userId: string },
|
||||
): void {
|
||||
const { userId } = ctx;
|
||||
|
||||
// TOOL: save_favorite (FAV-01)
|
||||
server.registerTool(
|
||||
"save_favorite",
|
||||
{
|
||||
description:
|
||||
"Bookmark an entity so the user can return to it later (upsert by entityId). " +
|
||||
"Inputs: entityId (string, required) -- the unique entity id; pluginId (string, required) -- the plugin that owns the entity; " +
|
||||
"name (string, optional) -- a human-readable label, defaults to entityId. " +
|
||||
"Output: text 'Saved favorite: <label>'. " +
|
||||
"Example: save_favorite({ entityId: 'AFR123', pluginId: 'flights', name: 'Air France 123' }).",
|
||||
inputSchema: {
|
||||
entityId: z.string().min(1).describe("Unique entity identifier"),
|
||||
pluginId: z.string().min(1).describe("Plugin that owns this entity"),
|
||||
name: z
|
||||
.string()
|
||||
.optional()
|
||||
.describe("Human-readable label for the bookmark (defaults to entityId)"),
|
||||
},
|
||||
},
|
||||
async (args) => {
|
||||
try {
|
||||
const label = args.name ?? args.entityId;
|
||||
await prisma.favorite.upsert({
|
||||
where: favoriteWhere(userId, args.entityId),
|
||||
update: {
|
||||
pluginId: args.pluginId,
|
||||
label,
|
||||
lastSeen: new Date(),
|
||||
},
|
||||
create: {
|
||||
userId,
|
||||
entityId: args.entityId,
|
||||
pluginId: args.pluginId,
|
||||
label,
|
||||
pluginName: args.pluginId,
|
||||
lastSeen: new Date(),
|
||||
},
|
||||
});
|
||||
return textResult(`Saved favorite: ${label}`);
|
||||
} catch (err) {
|
||||
console.error("[favoritesTools] save_favorite failed:", err);
|
||||
return textResult("save_favorite failed");
|
||||
}
|
||||
},
|
||||
);
|
||||
|
||||
// TOOL: list_favorites (FAV-02)
|
||||
server.registerTool(
|
||||
"list_favorites",
|
||||
{
|
||||
description:
|
||||
"List the authenticated user's bookmarked entities, most recently seen first. " +
|
||||
"Inputs: none. " +
|
||||
"Output: a JSON array of favorites, each with { id, userId, entityId, pluginId, label, pluginName, lastSeen, status }, " +
|
||||
"where status is 'live' if the entity currently resolves on an active globe session, otherwise 'stale'. " +
|
||||
"With no active session ALL entries are reported 'stale'. Returns [] when there are no favorites. " +
|
||||
"Example: list_favorites({}) -> [{ entityId: 'AFR123', pluginId: 'flights', label: 'Air France 123', status: 'live' }].",
|
||||
inputSchema: {},
|
||||
},
|
||||
async () => {
|
||||
try {
|
||||
const favorites = await prisma.favorite.findMany({
|
||||
where: { userId },
|
||||
orderBy: { lastSeen: "desc" },
|
||||
});
|
||||
if (favorites.length === 0) return textResult(JSON.stringify([]));
|
||||
|
||||
const sessions = await readActiveSessions(userId);
|
||||
const hasSession = sessions.length > 0;
|
||||
|
||||
const results = await Promise.all(
|
||||
favorites.map(async (fav) => {
|
||||
if (!hasSession) {
|
||||
return { ...fav, status: "stale" as const };
|
||||
}
|
||||
const detail = await getEntityDetails(fav.pluginId, fav.entityId);
|
||||
return { ...fav, status: detail !== null ? ("live" as const) : ("stale" as const) };
|
||||
}),
|
||||
);
|
||||
return textResult(JSON.stringify(results));
|
||||
} catch (err) {
|
||||
console.error("[favoritesTools] list_favorites failed:", err);
|
||||
return textResult("list_favorites failed");
|
||||
}
|
||||
},
|
||||
);
|
||||
|
||||
// TOOL: remove_favorite (FAV-03)
|
||||
server.registerTool(
|
||||
"remove_favorite",
|
||||
{
|
||||
description:
|
||||
"Remove a bookmarked entity from the authenticated user's favorites. " +
|
||||
"Inputs: entityId (string, required) -- the entity id to remove. " +
|
||||
"Output: text 'Removed favorite: <entityId>'. " +
|
||||
"Example: remove_favorite({ entityId: 'AFR123' }).",
|
||||
inputSchema: {
|
||||
entityId: z.string().min(1).describe("Entity identifier to remove from favorites"),
|
||||
},
|
||||
},
|
||||
async (args) => {
|
||||
try {
|
||||
await prisma.favorite.delete({
|
||||
where: favoriteWhere(userId, args.entityId),
|
||||
});
|
||||
return textResult(`Removed favorite: ${args.entityId}`);
|
||||
} catch (err) {
|
||||
console.error("[favoritesTools] remove_favorite failed:", err);
|
||||
return textResult("remove_favorite failed");
|
||||
}
|
||||
},
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,107 @@
|
||||
import { describe, it, expect, vi, beforeEach } from "vitest";
|
||||
|
||||
vi.mock("@/lib/globeCommandQueue");
|
||||
vi.mock("@/lib/mcpSessionCatalog");
|
||||
|
||||
// RED: ./filterTools does not exist yet. This import fails at collection time,
|
||||
// locking the three-tool contract (set_filter, clear_filter, get_plugin_filters).
|
||||
import { registerFilterTools } from "./filterTools";
|
||||
import { enqueueGlobeCommand, resolveActiveSessionId } from "@/lib/globeCommandQueue";
|
||||
import { readSessionCatalog } from "@/lib/mcpSessionCatalog";
|
||||
|
||||
const mockEnqueue = vi.mocked(enqueueGlobeCommand);
|
||||
const mockResolveActiveSessionId = vi.mocked(resolveActiveSessionId);
|
||||
const mockReadSessionCatalog = vi.mocked(readSessionCatalog);
|
||||
|
||||
const handlers: Record<string, (args: unknown) => unknown> = {};
|
||||
const mockServer = {
|
||||
registerTool: vi.fn((name: string, _schema: unknown, handler: (args: unknown) => unknown) => {
|
||||
handlers[name] = handler;
|
||||
}),
|
||||
};
|
||||
|
||||
const ctx = { userId: "u1" };
|
||||
|
||||
function textOf(result: unknown): string {
|
||||
return (result as { content: Array<{ text: string }> }).content[0].text;
|
||||
}
|
||||
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
Object.keys(handlers).forEach((k) => delete handlers[k]);
|
||||
mockResolveActiveSessionId.mockResolvedValue("sess-abc");
|
||||
registerFilterTools(mockServer as never, ctx);
|
||||
});
|
||||
|
||||
describe("set_filter tool handler", () => {
|
||||
it("enqueues a setFilter command with pluginId and filters", async () => {
|
||||
await handlers["set_filter"]({
|
||||
pluginId: "flights",
|
||||
filters: { status: { type: "select", values: ["airborne"] } },
|
||||
});
|
||||
|
||||
expect(mockEnqueue).toHaveBeenCalledWith(
|
||||
"u1",
|
||||
"sess-abc",
|
||||
{ type: "setFilter", pluginId: "flights", filters: { status: { type: "select", values: ["airborne"] } } },
|
||||
);
|
||||
});
|
||||
|
||||
it("returns NO_SESSION text and does not enqueue when no active session", async () => {
|
||||
mockResolveActiveSessionId.mockResolvedValue(null);
|
||||
|
||||
const result = await handlers["set_filter"]({ pluginId: "flights", filters: {} });
|
||||
|
||||
expect(textOf(result)).toMatch(/no active globe session/i);
|
||||
expect(mockEnqueue).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
|
||||
describe("clear_filter tool handler", () => {
|
||||
it("enqueues clearFilter without a pluginId field when pluginId omitted", async () => {
|
||||
await handlers["clear_filter"]({});
|
||||
|
||||
expect(mockEnqueue).toHaveBeenCalledWith("u1", "sess-abc", { type: "clearFilter" });
|
||||
});
|
||||
|
||||
it("enqueues clearFilter with pluginId when provided", async () => {
|
||||
await handlers["clear_filter"]({ pluginId: "flights" });
|
||||
|
||||
expect(mockEnqueue).toHaveBeenCalledWith("u1", "sess-abc", { type: "clearFilter", pluginId: "flights" });
|
||||
});
|
||||
});
|
||||
|
||||
describe("get_plugin_filters tool handler", () => {
|
||||
it("returns the plugin's filterDefinitions array as JSON", async () => {
|
||||
const defs = [{ id: "status", label: "Status", type: "select", propertyKey: "status" }];
|
||||
mockReadSessionCatalog.mockResolvedValue({
|
||||
tools: [],
|
||||
capabilities: [],
|
||||
filterDefinitions: { flights: defs },
|
||||
} as never);
|
||||
|
||||
const result = await handlers["get_plugin_filters"]({ pluginId: "flights" });
|
||||
|
||||
expect(JSON.parse(textOf(result))).toEqual(defs);
|
||||
});
|
||||
|
||||
it("returns [] when there is no active session", async () => {
|
||||
mockResolveActiveSessionId.mockResolvedValue(null);
|
||||
|
||||
const result = await handlers["get_plugin_filters"]({ pluginId: "flights" });
|
||||
|
||||
expect(JSON.parse(textOf(result))).toEqual([]);
|
||||
});
|
||||
|
||||
it("returns [] when catalog has no entry for the plugin", async () => {
|
||||
mockReadSessionCatalog.mockResolvedValue({
|
||||
tools: [],
|
||||
capabilities: [],
|
||||
filterDefinitions: {},
|
||||
} as never);
|
||||
|
||||
const result = await handlers["get_plugin_filters"]({ pluginId: "flights" });
|
||||
|
||||
expect(JSON.parse(textOf(result))).toEqual([]);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,169 @@
|
||||
/**
|
||||
* MCP Filter Tool registrar (Phase 23 Wave 2 -- 23-02).
|
||||
*
|
||||
* Registers three MCP tools that let an AI agent filter the live globe:
|
||||
*
|
||||
* set_filter -- push filter values to a plugin layer (FILT-01)
|
||||
* clear_filter -- clear one plugin's filters, or all filters (FILT-02)
|
||||
* get_plugin_filters -- read a plugin's declared filterable fields (FILT-03)
|
||||
*
|
||||
* set_filter / clear_filter enqueue a GlobeCommand via enqueueGlobeCommand; the
|
||||
* browser drains the queue over the SSE bridge and applies them to filterSlice.
|
||||
* get_plugin_filters reads the browser-published session catalog (D-05).
|
||||
*
|
||||
* Security: userId comes ONLY from ctx (the verified auth result). It is never
|
||||
* read from tool arguments. sessionId may come from args (scopes the tab) or is
|
||||
* resolved from the user's active ZSET entry.
|
||||
*/
|
||||
|
||||
import { z } from "zod";
|
||||
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
||||
import { enqueueGlobeCommand, resolveActiveSessionId } from "@/lib/globeCommandQueue";
|
||||
import { readSessionCatalog } from "@/lib/mcpSessionCatalog";
|
||||
import { filterValueSchema } from "@/lib/mcp/filterSchemas";
|
||||
import type { GlobeCommand } from "@/core/globe/types/GlobeCommand";
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Shared helpers
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
type McpTextResult = { content: [{ type: "text"; text: string }] };
|
||||
|
||||
function textResult(text: string): McpTextResult {
|
||||
return { content: [{ type: "text", text }] };
|
||||
}
|
||||
|
||||
const NO_SESSION_RESULT = textResult("no active globe session to control");
|
||||
|
||||
/**
|
||||
* Resolves the session to use: explicit arg takes precedence, falling back to
|
||||
* the most-recently-active session for this user. Returns null if none is live.
|
||||
*/
|
||||
async function resolveSession(
|
||||
userId: string,
|
||||
argSessionId: string | undefined,
|
||||
): Promise<string | null> {
|
||||
if (argSessionId !== undefined && argSessionId !== "") {
|
||||
return argSessionId;
|
||||
}
|
||||
return resolveActiveSessionId(userId);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Public registrar
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
export function registerFilterTools(
|
||||
server: McpServer,
|
||||
ctx: { userId: string },
|
||||
): void {
|
||||
const { userId } = ctx;
|
||||
|
||||
// TOOL: set_filter (FILT-01)
|
||||
server.registerTool(
|
||||
"set_filter",
|
||||
{
|
||||
description:
|
||||
"Apply one or more filters to a plugin's layer on the live globe (no page reload). " +
|
||||
"Inputs: pluginId (string, required) -- the plugin whose layer to filter, e.g. 'flights'; " +
|
||||
"filters (object, required) -- a map of filterId -> filter value, where each value is one of " +
|
||||
"{ type: 'text', value: string } | { type: 'select', values: string[] } | { type: 'range', min: number, max: number } | { type: 'boolean', value: boolean }; " +
|
||||
"sessionId (string, optional) -- target a specific tab; omit for the most-recently-active tab. " +
|
||||
"Discover valid filter ids and value types via get_plugin_filters. " +
|
||||
"Output: text 'set_filter command enqueued for <pluginId> (N filter(s))', or 'no active globe session to control'. " +
|
||||
"Example: set_filter({ pluginId: 'flights', filters: { status: { type: 'select', values: ['airborne'] } } }).",
|
||||
inputSchema: {
|
||||
pluginId: z.string().min(1).describe("Plugin whose layer to filter, e.g. 'flights'"),
|
||||
filters: z
|
||||
.record(z.string(), filterValueSchema)
|
||||
.describe("Map of filterId -> filter value. Discover valid filter ids via get_plugin_filters."),
|
||||
sessionId: z.string().optional().describe("Target globe session id. Omit to target most-recently-active tab."),
|
||||
},
|
||||
},
|
||||
async (args) => {
|
||||
try {
|
||||
const sessionId = await resolveSession(userId, args.sessionId);
|
||||
if (sessionId === null) return NO_SESSION_RESULT;
|
||||
|
||||
const cmd: GlobeCommand = {
|
||||
type: "setFilter",
|
||||
pluginId: args.pluginId,
|
||||
filters: args.filters,
|
||||
};
|
||||
await enqueueGlobeCommand(userId, sessionId, cmd);
|
||||
return textResult(
|
||||
`set_filter command enqueued for '${args.pluginId}' (${Object.keys(args.filters).length} filter(s))`,
|
||||
);
|
||||
} catch (err) {
|
||||
console.error("[filterTools] set_filter failed:", err);
|
||||
return textResult("set_filter command failed");
|
||||
}
|
||||
},
|
||||
);
|
||||
|
||||
// TOOL: clear_filter (FILT-02)
|
||||
server.registerTool(
|
||||
"clear_filter",
|
||||
{
|
||||
description:
|
||||
"Clear active filters on the live globe in one command. " +
|
||||
"Inputs: pluginId (string, optional) -- clear just that plugin's filters; omit to clear ALL filters across every plugin; " +
|
||||
"sessionId (string, optional) -- target a specific tab; omit for the most-recently-active tab. " +
|
||||
"Output: text 'clear_filter enqueued for <pluginId>' or 'clear_filter enqueued for ALL plugins', or 'no active globe session to control'. " +
|
||||
"Example: clear_filter({ pluginId: 'flights' }) or clear_filter({}).",
|
||||
inputSchema: {
|
||||
pluginId: z.string().optional().describe("Plugin whose filters to clear. Omit to clear ALL filters on the globe."),
|
||||
sessionId: z.string().optional().describe("Target globe session id. Omit to target most-recently-active tab."),
|
||||
},
|
||||
},
|
||||
async (args) => {
|
||||
try {
|
||||
const sessionId = await resolveSession(userId, args.sessionId);
|
||||
if (sessionId === null) return NO_SESSION_RESULT;
|
||||
|
||||
const cmd: GlobeCommand = {
|
||||
type: "clearFilter",
|
||||
...(args.pluginId !== undefined && { pluginId: args.pluginId }),
|
||||
};
|
||||
await enqueueGlobeCommand(userId, sessionId, cmd);
|
||||
return textResult(
|
||||
args.pluginId
|
||||
? `clear_filter enqueued for '${args.pluginId}'`
|
||||
: "clear_filter enqueued for ALL plugins",
|
||||
);
|
||||
} catch (err) {
|
||||
console.error("[filterTools] clear_filter failed:", err);
|
||||
return textResult("clear_filter command failed");
|
||||
}
|
||||
},
|
||||
);
|
||||
|
||||
// TOOL: get_plugin_filters (FILT-03)
|
||||
server.registerTool(
|
||||
"get_plugin_filters",
|
||||
{
|
||||
description:
|
||||
"List the filterable fields a plugin has declared (via its getFilterDefinitions), so you can build a valid set_filter call. " +
|
||||
"Inputs: pluginId (string, required) -- the plugin to inspect. " +
|
||||
"Output: a JSON array of FilterDefinition, each { id, label, type: 'text'|'select'|'range'|'boolean', propertyKey, options?: {value,label}[], range?: {min,max,step} }. " +
|
||||
"Returns [] when the plugin declares no filters or no globe session is active. " +
|
||||
"Example: get_plugin_filters({ pluginId: 'flights' }) -> [{ id: 'status', label: 'Status', type: 'select', propertyKey: 'flightStatus', options: [...] }].",
|
||||
inputSchema: {
|
||||
pluginId: z.string().min(1).describe("Plugin to inspect for declared filterable fields"),
|
||||
},
|
||||
},
|
||||
async (args) => {
|
||||
try {
|
||||
const sessionId = await resolveActiveSessionId(userId);
|
||||
if (!sessionId) return textResult("[]");
|
||||
|
||||
const catalog = await readSessionCatalog(userId, sessionId);
|
||||
const defs = catalog?.filterDefinitions?.[args.pluginId] ?? [];
|
||||
return textResult(JSON.stringify(defs));
|
||||
} catch (err) {
|
||||
console.error("[filterTools] get_plugin_filters failed:", err);
|
||||
return textResult("[]");
|
||||
}
|
||||
},
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,125 @@
|
||||
import { describe, it, expect, vi, beforeEach } from "vitest";
|
||||
|
||||
vi.mock("@/lib/nominatim");
|
||||
vi.mock("@/lib/geocodingRateLimit");
|
||||
vi.mock("@/lib/globeCommandQueue");
|
||||
|
||||
import { registerGeocodingTools } from "./geocodingTools";
|
||||
import { fetchGeocode } from "@/lib/nominatim";
|
||||
import { checkRateLimit } from "@/lib/geocodingRateLimit";
|
||||
import { enqueueGlobeCommand, resolveActiveSessionId } from "@/lib/globeCommandQueue";
|
||||
|
||||
const mockFetchGeocode = vi.mocked(fetchGeocode);
|
||||
const mockCheckRateLimit = vi.mocked(checkRateLimit);
|
||||
const mockEnqueueGlobeCommand = vi.mocked(enqueueGlobeCommand);
|
||||
const mockResolveActiveSessionId = vi.mocked(resolveActiveSessionId);
|
||||
|
||||
const handlers: Record<string, (args: unknown) => unknown> = {};
|
||||
const mockServer = {
|
||||
registerTool: vi.fn((name: string, _schema: unknown, handler: (args: unknown) => unknown) => {
|
||||
handlers[name] = handler;
|
||||
}),
|
||||
};
|
||||
|
||||
const ctx = { userId: "u1" };
|
||||
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
Object.keys(handlers).forEach((k) => delete handlers[k]);
|
||||
registerGeocodingTools(mockServer as never, ctx);
|
||||
});
|
||||
|
||||
describe("geocode_location tool handler", () => {
|
||||
it("returns structured result with lat/lng/name/bbox/importance when Nominatim returns results", async () => {
|
||||
mockCheckRateLimit.mockResolvedValue(undefined);
|
||||
mockFetchGeocode.mockResolvedValue([
|
||||
{
|
||||
lat: "51.5074",
|
||||
lon: "-0.1278",
|
||||
display_name: "London, UK",
|
||||
boundingbox: ["51.2868", "51.6919", "-0.5103", "0.3340"],
|
||||
importance: 0.9,
|
||||
},
|
||||
]);
|
||||
|
||||
const result = await handlers["geocode_location"]({ query: "London", limit: 1 });
|
||||
|
||||
expect(result).toMatchObject({
|
||||
content: expect.arrayContaining([
|
||||
expect.objectContaining({ type: "text" }),
|
||||
]),
|
||||
});
|
||||
const text = (result as { content: Array<{ text: string }> }).content[0].text;
|
||||
const parsed = JSON.parse(text);
|
||||
expect(parsed[0]).toMatchObject({ lat: expect.any(Number), lng: expect.any(Number), name: expect.any(String) });
|
||||
expect(parsed[0]).toHaveProperty("bbox");
|
||||
expect(parsed[0]).toHaveProperty("importance");
|
||||
});
|
||||
|
||||
it("returns 'no results' message when Nominatim returns empty array", async () => {
|
||||
mockCheckRateLimit.mockResolvedValue(undefined);
|
||||
mockFetchGeocode.mockResolvedValue([]);
|
||||
|
||||
const result = await handlers["geocode_location"]({ query: "xyznonexistent" });
|
||||
|
||||
const text = (result as { content: Array<{ text: string }> }).content[0].text;
|
||||
expect(text.toLowerCase()).toContain("no results");
|
||||
});
|
||||
|
||||
it("returns 'rate_limited' when checkRateLimit signals limit exceeded", async () => {
|
||||
mockCheckRateLimit.mockResolvedValue({ error: "rate_limited", retryAfterMs: 1000 });
|
||||
|
||||
const result = await handlers["geocode_location"]({ query: "Paris" });
|
||||
|
||||
const text = (result as { content: Array<{ text: string }> }).content[0].text;
|
||||
expect(text).toContain("rate_limited");
|
||||
});
|
||||
|
||||
it("clamps default limit to 5 and max limit to 20", async () => {
|
||||
mockCheckRateLimit.mockResolvedValue(undefined);
|
||||
mockFetchGeocode.mockResolvedValue([]);
|
||||
|
||||
await handlers["geocode_location"]({ query: "test" });
|
||||
expect(mockFetchGeocode).toHaveBeenCalledWith(expect.objectContaining({ limit: 5 }));
|
||||
|
||||
await handlers["geocode_location"]({ query: "test", limit: 100 });
|
||||
expect(mockFetchGeocode).toHaveBeenCalledWith(expect.objectContaining({ limit: 20 }));
|
||||
});
|
||||
});
|
||||
|
||||
describe("fly_to tool handler", () => {
|
||||
it("calls enqueueGlobeCommand with flyTo command for valid lat/lng", async () => {
|
||||
mockResolveActiveSessionId.mockResolvedValue("sess-abc");
|
||||
mockEnqueueGlobeCommand.mockResolvedValue(undefined);
|
||||
|
||||
await handlers["fly_to"]({ lat: 51.5, lng: -0.1 });
|
||||
|
||||
expect(mockEnqueueGlobeCommand).toHaveBeenCalledWith(
|
||||
"u1",
|
||||
"sess-abc",
|
||||
expect.objectContaining({ type: "flyTo", lat: 51.5, lng: -0.1 }),
|
||||
);
|
||||
});
|
||||
|
||||
it("returns NO_SESSION_RESULT text when no active session exists", async () => {
|
||||
mockResolveActiveSessionId.mockResolvedValue(null);
|
||||
|
||||
const result = await handlers["fly_to"]({ lat: 51.5, lng: -0.1 });
|
||||
|
||||
const text = (result as { content: Array<{ text: string }> }).content[0].text;
|
||||
expect(text).toMatch(/no.*(session|globe)/i);
|
||||
});
|
||||
|
||||
it("includes bbox in enqueueGlobeCommand call when bbox is provided", async () => {
|
||||
mockResolveActiveSessionId.mockResolvedValue("sess-abc");
|
||||
mockEnqueueGlobeCommand.mockResolvedValue(undefined);
|
||||
|
||||
await handlers["fly_to"]({ lat: 51.5, lng: -0.1, bbox: [-1, 50, 1, 52] });
|
||||
|
||||
expect(mockEnqueueGlobeCommand).toHaveBeenCalledWith(
|
||||
"u1",
|
||||
"sess-abc",
|
||||
expect.objectContaining({ bbox: [-1, 50, 1, 52] }),
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,206 @@
|
||||
/**
|
||||
* MCP Geocoding Tool registrar (Phase 22 Wave 2 -- 22-02).
|
||||
*
|
||||
* Registers two MCP tools:
|
||||
* geocode_location -- resolve a place name/address to coordinates via Nominatim
|
||||
* (GEO-01), with a per-user rate limit + 24h Redis cache (GEO-03)
|
||||
* fly_to -- enqueue a flyTo GlobeCommand to move the browser camera (GEO-02)
|
||||
*
|
||||
* Security: userId comes ONLY from ctx (verified auth result), never from tool
|
||||
* arguments. The Nominatim URL is hardcoded; the user query is injected via
|
||||
* URLSearchParams inside fetchGeocode (no string concatenation).
|
||||
*/
|
||||
|
||||
import { z } from "zod";
|
||||
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
||||
import { enqueueGlobeCommand, resolveActiveSessionId } from "@/lib/globeCommandQueue";
|
||||
import type { GlobeCommand } from "@/core/globe/types/GlobeCommand";
|
||||
import { fetchGeocode } from "@/lib/nominatim";
|
||||
import type { RawNominatimItem, NominatimResult } from "@/lib/nominatim";
|
||||
import { checkRateLimit } from "@/lib/geocodingRateLimit";
|
||||
import { redis } from "@/lib/redis";
|
||||
import { latSchema, lonSchema } from "@/lib/mcp/coordinateSchemas";
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Shared helpers
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
type McpTextResult = { content: [{ type: "text"; text: string }] };
|
||||
|
||||
function textResult(text: string): McpTextResult {
|
||||
return { content: [{ type: "text", text }] };
|
||||
}
|
||||
|
||||
const NO_SESSION_RESULT = textResult("no active globe session to control");
|
||||
|
||||
/**
|
||||
* Normalize a raw Nominatim item to the public NominatimResult shape (D-06).
|
||||
* Kept local (not imported) so that test mocks of "@/lib/nominatim" -- which
|
||||
* only stub fetchGeocode -- do not stub out the normalization step.
|
||||
* Nominatim boundingbox is ["south","north","west","east"]; remap to
|
||||
* [west, south, east, north] numbers.
|
||||
*/
|
||||
function normalizeResult(r: RawNominatimItem): NominatimResult {
|
||||
const bb = r.boundingbox ?? ["0", "0", "0", "0"];
|
||||
return {
|
||||
lat: parseFloat(r.lat ?? "0"),
|
||||
lng: parseFloat(r.lon ?? "0"),
|
||||
name: r.name ?? "",
|
||||
name_en: r.namedetails?.["name:en"] ?? r.name ?? "",
|
||||
type: r.type ?? "",
|
||||
addresstype: r.addresstype ?? "",
|
||||
country: r.address?.country ?? "",
|
||||
display_name: r.display_name ?? "",
|
||||
bbox: [parseFloat(bb[2]), parseFloat(bb[0]), parseFloat(bb[3]), parseFloat(bb[1])],
|
||||
importance: r.importance ?? 0,
|
||||
};
|
||||
}
|
||||
|
||||
/** Best-effort cache read: a Redis outage degrades to a miss, never an error. */
|
||||
async function cacheGet(key: string): Promise<string | null> {
|
||||
try {
|
||||
return await redis.get(key);
|
||||
} catch (err) {
|
||||
console.warn("[geocodingTools] cache read failed (degrading to miss):", err);
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
/** Best-effort cache write: a Redis outage is logged and ignored. */
|
||||
async function cacheSet(key: string, value: string, ttlSeconds: number): Promise<void> {
|
||||
try {
|
||||
await redis.set(key, value, "EX", ttlSeconds);
|
||||
} catch (err) {
|
||||
console.warn("[geocodingTools] cache write failed (ignored):", err);
|
||||
}
|
||||
}
|
||||
|
||||
const DEFAULT_LIMIT = 5;
|
||||
const MAX_LIMIT = 20;
|
||||
const DEFAULT_ALTITUDE_M = 15_000;
|
||||
const CACHE_TTL_SECONDS = 86_400; // 24h
|
||||
|
||||
/**
|
||||
* Resolves the session to use: explicit arg takes precedence, falling back to
|
||||
* the most-recently-active session for this user. Returns null if none is live.
|
||||
*/
|
||||
async function resolveSession(
|
||||
userId: string,
|
||||
argSessionId: string | undefined,
|
||||
): Promise<string | null> {
|
||||
if (argSessionId !== undefined && argSessionId !== "") {
|
||||
return argSessionId;
|
||||
}
|
||||
return resolveActiveSessionId(userId);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Public registrar
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
export function registerGeocodingTools(
|
||||
server: McpServer,
|
||||
ctx: { userId: string },
|
||||
): void {
|
||||
const { userId } = ctx;
|
||||
|
||||
// GEO-01 + GEO-03: geocode_location
|
||||
server.registerTool(
|
||||
"geocode_location",
|
||||
{
|
||||
description:
|
||||
"Geocode a place name or address to coordinates and a bounding box via OpenStreetMap Nominatim. " +
|
||||
"Inputs: query (string, required) -- the place name or address; limit (integer 1-20, optional, default 5) -- max results. " +
|
||||
"Output: a JSON array of results sorted by importance, each with { lat, lng, name, name_en, type, addresstype, country, display_name, bbox: [west, south, east, north], importance }. " +
|
||||
"Returns the literal text 'no results found' when nothing matches. " +
|
||||
"Example: geocode_location({ query: 'Paris', limit: 3 }) -> [{ lat: 48.85, lng: 2.35, name: 'Paris', bbox: [...], ... }].",
|
||||
inputSchema: {
|
||||
query: z.string().min(1).describe("Location name or address to geocode"),
|
||||
limit: z
|
||||
.number()
|
||||
.int()
|
||||
.min(1)
|
||||
.max(MAX_LIMIT)
|
||||
.optional()
|
||||
.describe("Max results to return (default 5, max 20)"),
|
||||
},
|
||||
},
|
||||
async (args) => {
|
||||
try {
|
||||
const limit = Math.min(args.limit ?? DEFAULT_LIMIT, MAX_LIMIT);
|
||||
const cacheKey = `geocode:${args.query.toLowerCase().trim()}:${limit}`;
|
||||
|
||||
const cached = await cacheGet(cacheKey);
|
||||
if (cached) return textResult(cached);
|
||||
|
||||
const rateLimitResult = await checkRateLimit(userId);
|
||||
if (rateLimitResult) return textResult(JSON.stringify(rateLimitResult));
|
||||
|
||||
const raw = await fetchGeocode({ query: args.query, limit });
|
||||
if (raw.length === 0) return textResult("no results found");
|
||||
|
||||
const results = raw.map(normalizeResult);
|
||||
const json = JSON.stringify(results);
|
||||
await cacheSet(cacheKey, json, CACHE_TTL_SECONDS);
|
||||
return textResult(json);
|
||||
} catch (err) {
|
||||
console.error("[geocodingTools] geocode_location failed:", err);
|
||||
return textResult("geocode_location command failed");
|
||||
}
|
||||
},
|
||||
);
|
||||
|
||||
// GEO-02: fly_to
|
||||
server.registerTool(
|
||||
"fly_to",
|
||||
{
|
||||
description:
|
||||
"Fly the live globe camera to a coordinate, optionally fitting a bounding box in view. " +
|
||||
"Inputs: lat (number -90..90, required), lng (number -180..180, required), altitude (positive number metres, optional, default 15000), " +
|
||||
"bbox ([west, south, east, north] tuple, optional -- fit this box in view), sessionId (string, optional -- target a specific browser tab; omit for the most-recently-active tab). " +
|
||||
"Output: text 'fly_to command enqueued (...)' on success, or 'no active globe session to control' when no tab is live. " +
|
||||
"The camera moves over the SSE bridge with no page reload. " +
|
||||
"Example: fly_to({ lat: 48.85, lng: 2.35 }) or fly_to({ lat: 0, lng: 0, bbox: [2.2, 48.8, 2.5, 48.9] }).",
|
||||
inputSchema: {
|
||||
lat: latSchema.describe("Latitude [-90, 90]"),
|
||||
lng: lonSchema.describe("Longitude [-180, 180]"),
|
||||
altitude: z
|
||||
.number()
|
||||
.positive()
|
||||
.optional()
|
||||
.describe("Altitude in metres above ellipsoid (default 15000)"),
|
||||
bbox: z
|
||||
.tuple([z.number(), z.number(), z.number(), z.number()])
|
||||
.optional()
|
||||
.describe("[west, south, east, north] bounding box to fit in view"),
|
||||
sessionId: z
|
||||
.string()
|
||||
.optional()
|
||||
.describe("Target globe session id. Omit to target most-recently-active tab."),
|
||||
},
|
||||
},
|
||||
async (args) => {
|
||||
try {
|
||||
const sessionId = await resolveSession(userId, args.sessionId);
|
||||
if (sessionId === null) return NO_SESSION_RESULT;
|
||||
|
||||
const cmd: GlobeCommand = {
|
||||
type: "flyTo",
|
||||
lat: args.lat,
|
||||
lng: args.lng,
|
||||
alt: args.altitude ?? DEFAULT_ALTITUDE_M,
|
||||
...(args.bbox ? { bbox: args.bbox } : {}),
|
||||
};
|
||||
await enqueueGlobeCommand(userId, sessionId, cmd);
|
||||
|
||||
const label = args.bbox
|
||||
? `bbox=[${args.bbox.join(",")}]`
|
||||
: `lat=${args.lat}, lng=${args.lng}, alt=${args.altitude ?? DEFAULT_ALTITUDE_M}`;
|
||||
return textResult(`fly_to command enqueued (${label})`);
|
||||
} catch (err) {
|
||||
console.error("[geocodingTools] fly_to failed:", err);
|
||||
return textResult("fly_to command failed");
|
||||
}
|
||||
},
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,381 @@
|
||||
/**
|
||||
* RED test scaffold for registerGlobeCommandTools (Phase 19a Wave 0).
|
||||
*
|
||||
* These tests INTENTIONALLY FAIL because globeCommandTools.ts does not exist yet.
|
||||
* They lock the following contracts:
|
||||
*
|
||||
* TOOL-01 All four tools are registered: pan_globe, focus_entity, toggle_layer, set_timeline
|
||||
* TOOL-02 pan_globe with explicit sessionId calls enqueueGlobeCommand directly (no resolve)
|
||||
* TOOL-03 toggle_layer without sessionId calls resolveActiveSessionId then enqueueGlobeCommand
|
||||
* TOOL-04 When resolveActiveSessionId returns null, handler returns graceful result, no enqueue
|
||||
* TOOL-05 userId comes ONLY from ctx, never from tool args
|
||||
*/
|
||||
|
||||
import { describe, it, expect, vi, beforeEach } from "vitest";
|
||||
import { registerGlobeCommandTools, latSchema, lonSchema, altSchema } from "./globeCommandTools";
|
||||
import { isValidGlobeCommand } from "@/core/globe/types/GlobeCommand";
|
||||
import { latSchema as sharedLatSchema, lonSchema as sharedLonSchema } from "@/lib/mcp/coordinateSchemas";
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Mock @/lib/globeCommandQueue
|
||||
// vi.mock is hoisted above const declarations, so mock objects must be
|
||||
// declared with vi.hoisted() to be accessible inside the factory function.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
const { mockEnqueue, mockResolveSessionId } = vi.hoisted(() => ({
|
||||
mockEnqueue: vi.fn().mockResolvedValue(undefined),
|
||||
mockResolveSessionId: vi.fn().mockResolvedValue("resolved-session"),
|
||||
}));
|
||||
|
||||
vi.mock("@/lib/globeCommandQueue", () => ({
|
||||
enqueueGlobeCommand: mockEnqueue,
|
||||
resolveActiveSessionId: mockResolveSessionId,
|
||||
}));
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Fake McpServer — records registered tools
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
type ToolHandler = (input: Record<string, unknown>) => Promise<{ content: [{ type: "text"; text: string }] }>;
|
||||
|
||||
function makeFakeServer() {
|
||||
const tools = new Map<string, ToolHandler>();
|
||||
const server = {
|
||||
registerTool: vi.fn((name: string, _def: unknown, handler: ToolHandler) => {
|
||||
tools.set(name, handler);
|
||||
}),
|
||||
};
|
||||
return { server, tools };
|
||||
}
|
||||
|
||||
beforeEach(() => {
|
||||
vi.resetAllMocks();
|
||||
mockEnqueue.mockResolvedValue(undefined);
|
||||
mockResolveSessionId.mockResolvedValue("resolved-session");
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// TOOL-01: all four tools are registered
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("registerGlobeCommandTools registration (TOOL-01)", () => {
|
||||
it("registers pan_globe, focus_entity, toggle_layer, and set_timeline", () => {
|
||||
const { server, tools } = makeFakeServer();
|
||||
|
||||
registerGlobeCommandTools(server as unknown as import("@modelcontextprotocol/sdk/server/mcp.js").McpServer, { userId: "u1" });
|
||||
|
||||
expect(tools.has("pan_globe")).toBe(true);
|
||||
expect(tools.has("focus_entity")).toBe(true);
|
||||
expect(tools.has("toggle_layer")).toBe(true);
|
||||
expect(tools.has("set_timeline")).toBe(true);
|
||||
});
|
||||
|
||||
it("calls server.registerTool exactly four times", () => {
|
||||
const { server } = makeFakeServer();
|
||||
|
||||
registerGlobeCommandTools(server as unknown as import("@modelcontextprotocol/sdk/server/mcp.js").McpServer, { userId: "u1" });
|
||||
|
||||
expect(server.registerTool).toHaveBeenCalledTimes(4);
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// TOOL-02: pan_globe with explicit sessionId bypasses resolveActiveSessionId
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("pan_globe handler (TOOL-02)", () => {
|
||||
it("calls enqueueGlobeCommand with userId, sessionId, and pan GlobeCommand", async () => {
|
||||
const { server, tools } = makeFakeServer();
|
||||
registerGlobeCommandTools(server as unknown as import("@modelcontextprotocol/sdk/server/mcp.js").McpServer, { userId: "u1" });
|
||||
|
||||
const handler = tools.get("pan_globe")!;
|
||||
await handler({ lat: 1, lon: 2, alt: 3, sessionId: "s9" });
|
||||
|
||||
expect(mockEnqueue).toHaveBeenCalledWith(
|
||||
"u1",
|
||||
"s9",
|
||||
expect.objectContaining({ type: "pan", lat: 1, lon: 2, alt: 3 }),
|
||||
);
|
||||
});
|
||||
|
||||
it("does NOT call resolveActiveSessionId when sessionId is provided", async () => {
|
||||
const { server, tools } = makeFakeServer();
|
||||
registerGlobeCommandTools(server as unknown as import("@modelcontextprotocol/sdk/server/mcp.js").McpServer, { userId: "u1" });
|
||||
|
||||
const handler = tools.get("pan_globe")!;
|
||||
await handler({ lat: 1, lon: 2, alt: 3, sessionId: "explicit-session" });
|
||||
|
||||
expect(mockResolveSessionId).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("returns a success content result", async () => {
|
||||
const { server, tools } = makeFakeServer();
|
||||
registerGlobeCommandTools(server as unknown as import("@modelcontextprotocol/sdk/server/mcp.js").McpServer, { userId: "u1" });
|
||||
|
||||
const handler = tools.get("pan_globe")!;
|
||||
const result = await handler({ lat: 40.7, lon: -74.0, alt: 500000, sessionId: "s9" });
|
||||
|
||||
expect(result).toHaveProperty("content");
|
||||
expect(Array.isArray(result.content)).toBe(true);
|
||||
expect(result.content[0]).toHaveProperty("type", "text");
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// TOOL-03: toggle_layer without sessionId calls resolveActiveSessionId
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("toggle_layer handler — session resolution (TOOL-03)", () => {
|
||||
it("calls resolveActiveSessionId(userId) when no sessionId is provided", async () => {
|
||||
const { server, tools } = makeFakeServer();
|
||||
registerGlobeCommandTools(server as unknown as import("@modelcontextprotocol/sdk/server/mcp.js").McpServer, { userId: "u1" });
|
||||
|
||||
const handler = tools.get("toggle_layer")!;
|
||||
await handler({ layerId: "ais" });
|
||||
|
||||
expect(mockResolveSessionId).toHaveBeenCalledWith("u1");
|
||||
});
|
||||
|
||||
it("enqueues using the resolved sessionId", async () => {
|
||||
mockResolveSessionId.mockResolvedValue("resolved-s99");
|
||||
const { server, tools } = makeFakeServer();
|
||||
registerGlobeCommandTools(server as unknown as import("@modelcontextprotocol/sdk/server/mcp.js").McpServer, { userId: "u1" });
|
||||
|
||||
const handler = tools.get("toggle_layer")!;
|
||||
await handler({ layerId: "aviation" });
|
||||
|
||||
expect(mockEnqueue).toHaveBeenCalledWith(
|
||||
"u1",
|
||||
"resolved-s99",
|
||||
expect.objectContaining({ type: "toggleLayer", layerId: "aviation" }),
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// TOOL-04: graceful result when no active session
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("handler graceful fallback — no active session (TOOL-04)", () => {
|
||||
beforeEach(() => {
|
||||
mockResolveSessionId.mockResolvedValue(null);
|
||||
});
|
||||
|
||||
it("does NOT call enqueueGlobeCommand when resolveActiveSessionId returns null", async () => {
|
||||
const { server, tools } = makeFakeServer();
|
||||
registerGlobeCommandTools(server as unknown as import("@modelcontextprotocol/sdk/server/mcp.js").McpServer, { userId: "u1" });
|
||||
|
||||
const handler = tools.get("toggle_layer")!;
|
||||
await handler({ layerId: "ais" });
|
||||
|
||||
expect(mockEnqueue).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("returns a content result mentioning no active globe session", async () => {
|
||||
const { server, tools } = makeFakeServer();
|
||||
registerGlobeCommandTools(server as unknown as import("@modelcontextprotocol/sdk/server/mcp.js").McpServer, { userId: "u1" });
|
||||
|
||||
const handler = tools.get("toggle_layer")!;
|
||||
const result = await handler({ layerId: "ais" });
|
||||
|
||||
expect(result.content[0].type).toBe("text");
|
||||
expect(result.content[0].text.toLowerCase()).toContain("no active");
|
||||
});
|
||||
|
||||
it("set_timeline also returns graceful result without enqueuing", async () => {
|
||||
const { server, tools } = makeFakeServer();
|
||||
registerGlobeCommandTools(server as unknown as import("@modelcontextprotocol/sdk/server/mcp.js").McpServer, { userId: "u1" });
|
||||
|
||||
const handler = tools.get("set_timeline")!;
|
||||
const result = await handler({ timeWindow: "24h" });
|
||||
|
||||
expect(mockEnqueue).not.toHaveBeenCalled();
|
||||
expect(result.content[0].text.toLowerCase()).toContain("no active");
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// TOOL-05: userId always from ctx, never from tool args
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("userId source invariant (TOOL-05)", () => {
|
||||
it("uses ctx.userId not a userId field in args", async () => {
|
||||
const { server, tools } = makeFakeServer();
|
||||
registerGlobeCommandTools(server as unknown as import("@modelcontextprotocol/sdk/server/mcp.js").McpServer, { userId: "ctx-user" });
|
||||
|
||||
const handler = tools.get("pan_globe")!;
|
||||
// Simulate a caller that supplies a userId in args — must be ignored
|
||||
await handler({ lat: 1, lon: 2, alt: 3, sessionId: "s1" });
|
||||
|
||||
const [calledUserId] = mockEnqueue.mock.calls[0] as [string, string, unknown];
|
||||
expect(calledUserId).toBe("ctx-user");
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// TOOL-06: coordinate schema bounds validation (latSchema / lonSchema / altSchema)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("coordinate schema bounds (TOOL-06)", () => {
|
||||
// latSchema
|
||||
it("latSchema accepts valid latitude", () => {
|
||||
expect(latSchema.safeParse(35.6762).success).toBe(true);
|
||||
expect(latSchema.safeParse(0).success).toBe(true);
|
||||
expect(latSchema.safeParse(-90).success).toBe(true);
|
||||
expect(latSchema.safeParse(90).success).toBe(true);
|
||||
});
|
||||
|
||||
it("latSchema rejects lat=999", () => {
|
||||
expect(latSchema.safeParse(999).success).toBe(false);
|
||||
});
|
||||
|
||||
it("latSchema rejects lat=-91", () => {
|
||||
expect(latSchema.safeParse(-91).success).toBe(false);
|
||||
});
|
||||
|
||||
it("latSchema rejects NaN", () => {
|
||||
expect(latSchema.safeParse(NaN).success).toBe(false);
|
||||
});
|
||||
|
||||
it("latSchema rejects Infinity", () => {
|
||||
expect(latSchema.safeParse(Infinity).success).toBe(false);
|
||||
});
|
||||
|
||||
// lonSchema
|
||||
it("lonSchema accepts valid longitude", () => {
|
||||
expect(lonSchema.safeParse(139.6503).success).toBe(true);
|
||||
expect(lonSchema.safeParse(-180).success).toBe(true);
|
||||
expect(lonSchema.safeParse(180).success).toBe(true);
|
||||
});
|
||||
|
||||
it("lonSchema rejects lon=181", () => {
|
||||
expect(lonSchema.safeParse(181).success).toBe(false);
|
||||
});
|
||||
|
||||
it("lonSchema rejects lon=-181", () => {
|
||||
expect(lonSchema.safeParse(-181).success).toBe(false);
|
||||
});
|
||||
|
||||
it("lonSchema rejects NaN", () => {
|
||||
expect(lonSchema.safeParse(NaN).success).toBe(false);
|
||||
});
|
||||
|
||||
// altSchema
|
||||
it("altSchema accepts valid altitude", () => {
|
||||
expect(altSchema.safeParse(2000000).success).toBe(true);
|
||||
expect(altSchema.safeParse(1).success).toBe(true);
|
||||
});
|
||||
|
||||
it("altSchema rejects alt=0", () => {
|
||||
expect(altSchema.safeParse(0).success).toBe(false);
|
||||
});
|
||||
|
||||
it("altSchema rejects negative altitude", () => {
|
||||
expect(altSchema.safeParse(-100).success).toBe(false);
|
||||
});
|
||||
|
||||
it("altSchema rejects Infinity", () => {
|
||||
expect(altSchema.safeParse(Infinity).success).toBe(false);
|
||||
});
|
||||
|
||||
it("altSchema rejects NaN", () => {
|
||||
expect(altSchema.safeParse(NaN).success).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// TOOL-07: isValidGlobeCommand rejects out-of-range coordinates
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("isValidGlobeCommand coordinate bounds (TOOL-07)", () => {
|
||||
it("accepts a valid pan command", () => {
|
||||
expect(isValidGlobeCommand({ type: "pan", lat: 35.6762, lon: 139.6503, alt: 2000000 })).toBe(true);
|
||||
});
|
||||
|
||||
it("rejects pan with lat=999", () => {
|
||||
expect(isValidGlobeCommand({ type: "pan", lat: 999, lon: 0, alt: 1000 })).toBe(false);
|
||||
});
|
||||
|
||||
it("rejects pan with lat=-91", () => {
|
||||
expect(isValidGlobeCommand({ type: "pan", lat: -91, lon: 0, alt: 1000 })).toBe(false);
|
||||
});
|
||||
|
||||
it("rejects pan with lon=181", () => {
|
||||
expect(isValidGlobeCommand({ type: "pan", lat: 0, lon: 181, alt: 1000 })).toBe(false);
|
||||
});
|
||||
|
||||
it("rejects pan with lon=-181", () => {
|
||||
expect(isValidGlobeCommand({ type: "pan", lat: 0, lon: -181, alt: 1000 })).toBe(false);
|
||||
});
|
||||
|
||||
it("rejects pan with alt=0", () => {
|
||||
expect(isValidGlobeCommand({ type: "pan", lat: 0, lon: 0, alt: 0 })).toBe(false);
|
||||
});
|
||||
|
||||
it("rejects pan with negative alt", () => {
|
||||
expect(isValidGlobeCommand({ type: "pan", lat: 0, lon: 0, alt: -500 })).toBe(false);
|
||||
});
|
||||
|
||||
it("rejects pan with NaN lat", () => {
|
||||
expect(isValidGlobeCommand({ type: "pan", lat: NaN, lon: 0, alt: 1000 })).toBe(false);
|
||||
});
|
||||
|
||||
it("rejects pan with Infinity alt", () => {
|
||||
expect(isValidGlobeCommand({ type: "pan", lat: 0, lon: 0, alt: Infinity })).toBe(false);
|
||||
});
|
||||
|
||||
it("accepts focusEntity with valid lat/lon", () => {
|
||||
expect(isValidGlobeCommand({ type: "focusEntity", lat: 35.6762, lon: 139.6503 })).toBe(true);
|
||||
});
|
||||
|
||||
it("accepts focusEntity with no lat/lon (entity-id only)", () => {
|
||||
expect(isValidGlobeCommand({ type: "focusEntity", entityId: "ent-1" })).toBe(true);
|
||||
});
|
||||
|
||||
it("rejects focusEntity with out-of-range lat", () => {
|
||||
expect(isValidGlobeCommand({ type: "focusEntity", lat: 91, lon: 0 })).toBe(false);
|
||||
});
|
||||
|
||||
it("rejects focusEntity with out-of-range lon", () => {
|
||||
expect(isValidGlobeCommand({ type: "focusEntity", lat: 0, lon: 200 })).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// TOOL-08: isValidGlobeCommand rejects NaN heading (isNumber requires isFinite)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("isValidGlobeCommand NaN heading rejection (TOOL-08)", () => {
|
||||
it("rejects a pan command with heading: NaN", () => {
|
||||
expect(isValidGlobeCommand({ type: "pan", lat: 0, lon: 0, alt: 1000, heading: NaN })).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// TOOL-09: get_entities_in_region schema bounds (latSchema / lonSchema shared module)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("get_entities_in_region coordinate schema bounds (TOOL-09)", () => {
|
||||
it("rejects north=999 (out-of-range latitude)", () => {
|
||||
expect(sharedLatSchema.safeParse(999).success).toBe(false);
|
||||
});
|
||||
|
||||
it("rejects west=-200 (out-of-range longitude)", () => {
|
||||
expect(sharedLonSchema.safeParse(-200).success).toBe(false);
|
||||
});
|
||||
|
||||
it("accepts a valid bounding box", () => {
|
||||
expect(sharedLatSchema.safeParse(51.5).success).toBe(true); // north
|
||||
expect(sharedLatSchema.safeParse(48.8).success).toBe(true); // south
|
||||
expect(sharedLonSchema.safeParse(-0.1).success).toBe(true); // west
|
||||
expect(sharedLonSchema.safeParse(2.3).success).toBe(true); // east
|
||||
});
|
||||
|
||||
it("rejects NaN for a latitude bound", () => {
|
||||
expect(sharedLatSchema.safeParse(NaN).success).toBe(false);
|
||||
});
|
||||
|
||||
it("rejects Infinity for a longitude bound", () => {
|
||||
expect(sharedLonSchema.safeParse(Infinity).success).toBe(false);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,200 @@
|
||||
/**
|
||||
* MCP Globe Command Tool registrar (Phase 19a Wave 2 -- 19-03).
|
||||
*
|
||||
* Registers four MCP tools that let an AI agent control the live globe in the
|
||||
* browser. Commands are enqueued to a per-session Redis list; the browser polls
|
||||
* GET /api/globe/commands to drain them (poll-based delivery, 19a transport).
|
||||
*
|
||||
* pan_globe -- fly the camera to a lat/lon/altitude
|
||||
* focus_entity -- point the camera at a known entity or coordinate
|
||||
* toggle_layer -- enable or disable a named plugin layer
|
||||
* set_timeline -- set playback time / window / mode
|
||||
*
|
||||
* Security: userId comes ONLY from ctx (the verified auth result). It is never
|
||||
* read from tool arguments. sessionId may come from args (scopes the tab) or is
|
||||
* resolved from the user's active ZSET entry.
|
||||
*/
|
||||
|
||||
import { z } from "zod";
|
||||
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
||||
import { enqueueGlobeCommand, resolveActiveSessionId } from "@/lib/globeCommandQueue";
|
||||
import { TIME_WINDOW_VALUES } from "@/core/globe/types/GlobeCommand";
|
||||
import type { GlobeCommand } from "@/core/globe/types/GlobeCommand";
|
||||
import { latSchema, lonSchema, altSchema } from "@/lib/mcp/coordinateSchemas";
|
||||
|
||||
// Re-export so existing tests that import from this module continue to work.
|
||||
export { latSchema, lonSchema, altSchema };
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Shared helpers
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
type McpTextResult = { content: [{ type: "text"; text: string }] };
|
||||
|
||||
function textResult(text: string): McpTextResult {
|
||||
return { content: [{ type: "text", text }] };
|
||||
}
|
||||
|
||||
const NO_SESSION_RESULT = textResult("no active globe session to control");
|
||||
|
||||
/**
|
||||
* Resolves the session to use: explicit arg takes precedence, falling back to
|
||||
* the most-recently-active session for this user. Returns null if none is live.
|
||||
*/
|
||||
async function resolveSession(
|
||||
userId: string,
|
||||
argSessionId: string | undefined,
|
||||
): Promise<string | null> {
|
||||
if (argSessionId !== undefined && argSessionId !== "") {
|
||||
return argSessionId;
|
||||
}
|
||||
return resolveActiveSessionId(userId);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Public registrar
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
export function registerGlobeCommandTools(
|
||||
server: McpServer,
|
||||
ctx: { userId: string },
|
||||
): void {
|
||||
const { userId } = ctx;
|
||||
|
||||
// TOOL-01: pan_globe
|
||||
server.registerTool(
|
||||
"pan_globe",
|
||||
{
|
||||
description:
|
||||
"Fly the globe camera to a geographic position. Provide lat/lon/alt (metres). Optional heading, pitch, and animation duration.",
|
||||
inputSchema: {
|
||||
lat: latSchema.describe("Latitude in decimal degrees [-90, 90]"),
|
||||
lon: lonSchema.describe("Longitude in decimal degrees [-180, 180]"),
|
||||
alt: altSchema.describe("Altitude in metres above the ellipsoid (must be > 0)"),
|
||||
heading: z.number().optional().describe("Camera heading in degrees (0 = north)"),
|
||||
pitch: z.number().optional().describe("Camera pitch in degrees (-90 = straight down)"),
|
||||
duration: z.number().optional().describe("Flight animation duration in seconds"),
|
||||
sessionId: z.string().optional().describe("Target globe session id. Obtain valid ids by reading the globe://sessions resource. Omit to target your most-recently-active browser tab."),
|
||||
},
|
||||
},
|
||||
async (args) => {
|
||||
try {
|
||||
const sessionId = await resolveSession(userId, args.sessionId);
|
||||
if (sessionId === null) return NO_SESSION_RESULT;
|
||||
|
||||
const cmd: GlobeCommand = {
|
||||
type: "pan",
|
||||
lat: args.lat,
|
||||
lon: args.lon,
|
||||
alt: args.alt,
|
||||
...(args.heading !== undefined && { heading: args.heading }),
|
||||
...(args.pitch !== undefined && { pitch: args.pitch }),
|
||||
...(args.duration !== undefined && { duration: args.duration }),
|
||||
};
|
||||
await enqueueGlobeCommand(userId, sessionId, cmd);
|
||||
return textResult(`Camera panning to lat=${args.lat}, lon=${args.lon}, alt=${args.alt}`);
|
||||
} catch (err) {
|
||||
console.error("[globeCommandTools] pan_globe failed:", err);
|
||||
return textResult("pan_globe command failed");
|
||||
}
|
||||
},
|
||||
);
|
||||
|
||||
// TOOL-02: focus_entity
|
||||
server.registerTool(
|
||||
"focus_entity",
|
||||
{
|
||||
description:
|
||||
"Point the globe camera at a geographic coordinate. Provide lat and lon to fly the camera there. " +
|
||||
"entityId is accepted but entity-id-to-coordinate resolution is not yet wired; always include lat/lon for a reliable camera move.",
|
||||
inputSchema: {
|
||||
entityId: z.string().optional().describe("Entity id (informational; coordinate resolution not yet supported -- also provide lat/lon)"),
|
||||
lat: latSchema.optional().describe("Latitude to focus on [-90, 90]"),
|
||||
lon: lonSchema.optional().describe("Longitude to focus on [-180, 180]"),
|
||||
sessionId: z.string().optional().describe("Target globe session id. Obtain valid ids by reading the globe://sessions resource. Omit to target your most-recently-active browser tab."),
|
||||
},
|
||||
},
|
||||
async (args) => {
|
||||
try {
|
||||
const sessionId = await resolveSession(userId, args.sessionId);
|
||||
if (sessionId === null) return NO_SESSION_RESULT;
|
||||
|
||||
const cmd: GlobeCommand = {
|
||||
type: "focusEntity",
|
||||
...(args.entityId !== undefined && { entityId: args.entityId }),
|
||||
...(args.lat !== undefined && { lat: args.lat }),
|
||||
...(args.lon !== undefined && { lon: args.lon }),
|
||||
};
|
||||
await enqueueGlobeCommand(userId, sessionId, cmd);
|
||||
return textResult(`Focus entity command enqueued (entityId=${args.entityId ?? "none"}, lat=${args.lat ?? "none"}, lon=${args.lon ?? "none"})`);
|
||||
} catch (err) {
|
||||
console.error("[globeCommandTools] focus_entity failed:", err);
|
||||
return textResult("focus_entity command failed");
|
||||
}
|
||||
},
|
||||
);
|
||||
|
||||
// TOOL-03: toggle_layer
|
||||
server.registerTool(
|
||||
"toggle_layer",
|
||||
{
|
||||
description:
|
||||
"Enable or disable a plugin data layer on the globe. Omit 'enabled' to toggle the current state.",
|
||||
inputSchema: {
|
||||
layerId: z.string().describe("The plugin/layer identifier to toggle"),
|
||||
enabled: z.boolean().optional().describe("True to enable, false to disable, omit to toggle"),
|
||||
sessionId: z.string().optional().describe("Target globe session id. Obtain valid ids by reading the globe://sessions resource. Omit to target your most-recently-active browser tab."),
|
||||
},
|
||||
},
|
||||
async (args) => {
|
||||
try {
|
||||
const sessionId = await resolveSession(userId, args.sessionId);
|
||||
if (sessionId === null) return NO_SESSION_RESULT;
|
||||
|
||||
const cmd: GlobeCommand = {
|
||||
type: "toggleLayer",
|
||||
layerId: args.layerId,
|
||||
...(args.enabled !== undefined && { enabled: args.enabled }),
|
||||
};
|
||||
await enqueueGlobeCommand(userId, sessionId, cmd);
|
||||
return textResult(`Layer '${args.layerId}' toggle command enqueued`);
|
||||
} catch (err) {
|
||||
console.error("[globeCommandTools] toggle_layer failed:", err);
|
||||
return textResult("toggle_layer command failed");
|
||||
}
|
||||
},
|
||||
);
|
||||
|
||||
// TOOL-04: set_timeline
|
||||
server.registerTool(
|
||||
"set_timeline",
|
||||
{
|
||||
description:
|
||||
"Set the globe timeline position, time window, or playback mode.",
|
||||
inputSchema: {
|
||||
currentTime: z.string().optional().describe("ISO 8601 datetime to seek to"),
|
||||
timeWindow: z.enum(TIME_WINDOW_VALUES).optional().describe("Time window: one of '1h', '6h', '24h', '48h', '7d'"),
|
||||
isPlaybackMode: z.boolean().optional().describe("True to start playback, false to pause"),
|
||||
sessionId: z.string().optional().describe("Target globe session id. Obtain valid ids by reading the globe://sessions resource. Omit to target your most-recently-active browser tab."),
|
||||
},
|
||||
},
|
||||
async (args) => {
|
||||
try {
|
||||
const sessionId = await resolveSession(userId, args.sessionId);
|
||||
if (sessionId === null) return NO_SESSION_RESULT;
|
||||
|
||||
const cmd: GlobeCommand = {
|
||||
type: "setTimeline",
|
||||
...(args.currentTime !== undefined && { currentTime: args.currentTime }),
|
||||
...(args.timeWindow !== undefined && { timeWindow: args.timeWindow }),
|
||||
...(args.isPlaybackMode !== undefined && { isPlaybackMode: args.isPlaybackMode }),
|
||||
};
|
||||
await enqueueGlobeCommand(userId, sessionId, cmd);
|
||||
return textResult("Timeline command enqueued");
|
||||
} catch (err) {
|
||||
console.error("[globeCommandTools] set_timeline failed:", err);
|
||||
return textResult("set_timeline command failed");
|
||||
}
|
||||
},
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,266 @@
|
||||
import { describe, it, expect, vi, beforeEach } from "vitest";
|
||||
import { registerGlobeResources } from "./globeResources";
|
||||
import {
|
||||
readGlobeState,
|
||||
readActiveSessions,
|
||||
} from "@/lib/globeStateStore";
|
||||
|
||||
vi.mock("@/lib/globeStateStore", () => ({
|
||||
readGlobeState: vi.fn(),
|
||||
readActiveSessions: vi.fn(),
|
||||
}));
|
||||
|
||||
const mockReadState = vi.mocked(readGlobeState);
|
||||
const mockReadSessions = vi.mocked(readActiveSessions);
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Fake MCP server — captures registerResource calls for assertion.
|
||||
// Shape mirrors the McpServer surface used by registerGlobeResources.
|
||||
// ---------------------------------------------------------------------------
|
||||
function makeFakeServer() {
|
||||
return {
|
||||
registerResource: vi.fn(),
|
||||
};
|
||||
}
|
||||
|
||||
beforeEach(() => {
|
||||
vi.resetAllMocks();
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// RSRC-02/03/04 — registerGlobeResources registration
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("registerGlobeResources — resource registration", () => {
|
||||
it("calls server.registerResource exactly three times (RSRC-02/03/04)", () => {
|
||||
const server = makeFakeServer();
|
||||
registerGlobeResources(server as never, { userId: "u1" });
|
||||
|
||||
expect(server.registerResource).toHaveBeenCalledTimes(3);
|
||||
});
|
||||
|
||||
it("registers globe://state/{sessionId} resource (RSRC-02)", () => {
|
||||
const server = makeFakeServer();
|
||||
registerGlobeResources(server as never, { userId: "u1" });
|
||||
|
||||
const uris = (server.registerResource.mock.calls as [string | { uriTemplate: string }, ...unknown[]][]).map(
|
||||
([uriOrTemplate]) =>
|
||||
typeof uriOrTemplate === "string" ? uriOrTemplate : uriOrTemplate.uriTemplate,
|
||||
);
|
||||
expect(uris.some((u: string) => u.includes("state"))).toBe(true);
|
||||
});
|
||||
|
||||
it("registers globe://sessions resource (RSRC-03)", () => {
|
||||
const server = makeFakeServer();
|
||||
registerGlobeResources(server as never, { userId: "u1" });
|
||||
|
||||
const uris = (server.registerResource.mock.calls as [string | { uriTemplate: string }, ...unknown[]][]).map(
|
||||
([uriOrTemplate]) =>
|
||||
typeof uriOrTemplate === "string" ? uriOrTemplate : uriOrTemplate.uriTemplate,
|
||||
);
|
||||
expect(uris.some((u: string) => u.includes("sessions"))).toBe(true);
|
||||
});
|
||||
|
||||
it("registers globe://layers resource (RSRC-04)", () => {
|
||||
const server = makeFakeServer();
|
||||
registerGlobeResources(server as never, { userId: "u1" });
|
||||
|
||||
const uris = (server.registerResource.mock.calls as [string | { uriTemplate: string }, ...unknown[]][]).map(
|
||||
([uriOrTemplate]) =>
|
||||
typeof uriOrTemplate === "string" ? uriOrTemplate : uriOrTemplate.uriTemplate,
|
||||
);
|
||||
expect(uris.some((u: string) => u.includes("layers"))).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// RSRC-02 — globe://state/{sessionId} handler
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("globe://state handler (RSRC-02)", () => {
|
||||
it("calls readGlobeState with injected userId 'u1' and the given sessionId", async () => {
|
||||
const snapshot = {
|
||||
viewport: { lat: 37.7, lon: -122.4, altitude: 500000, heading: 0, pitch: -90, roll: 0 },
|
||||
layers: {},
|
||||
timeline: {
|
||||
currentTime: "2026-01-15T12:00:00.000Z",
|
||||
timeWindow: "24h",
|
||||
isPlaybackMode: false,
|
||||
playbackTime: 1737000000000,
|
||||
playbackSpeed: 1,
|
||||
},
|
||||
selectedEntity: null,
|
||||
lastUpdate: 1737000000000,
|
||||
};
|
||||
mockReadState.mockResolvedValue(snapshot);
|
||||
|
||||
const server = makeFakeServer();
|
||||
registerGlobeResources(server as never, { userId: "u1" });
|
||||
|
||||
// Find the state resource handler (the call whose URI/template contains "state")
|
||||
const stateCall = (server.registerResource.mock.calls as [string | { uriTemplate: string }, ...unknown[]][]).find(
|
||||
([uriOrTemplate]) => {
|
||||
const s = typeof uriOrTemplate === "string" ? uriOrTemplate : uriOrTemplate.uriTemplate;
|
||||
return s.includes("state");
|
||||
},
|
||||
);
|
||||
expect(stateCall).toBeDefined();
|
||||
|
||||
// The handler is the last argument in the registerResource call
|
||||
const handler = stateCall![stateCall!.length - 1] as (
|
||||
uri: URL,
|
||||
params: Record<string, string>,
|
||||
) => Promise<unknown>;
|
||||
|
||||
const uri = new URL("globe://state/s1");
|
||||
const result = await handler(uri, { sessionId: "s1" });
|
||||
|
||||
expect(mockReadState).toHaveBeenCalledWith("u1", "s1");
|
||||
|
||||
// Response shape: { contents: [{ uri, mimeType, text }] }
|
||||
expect(result).toHaveProperty("contents");
|
||||
const contents = (result as { contents: unknown[] }).contents;
|
||||
expect(Array.isArray(contents)).toBe(true);
|
||||
expect(contents[0]).toHaveProperty("mimeType", "application/json");
|
||||
expect(contents[0]).toHaveProperty("text");
|
||||
const parsed = JSON.parse((contents[0] as { text: string }).text);
|
||||
expect(parsed).toEqual(snapshot);
|
||||
});
|
||||
|
||||
it("uses injected userId 'u1' — never a hardcoded value", async () => {
|
||||
mockReadState.mockResolvedValue(null);
|
||||
|
||||
const server = makeFakeServer();
|
||||
// Register with a different userId to confirm scoping
|
||||
registerGlobeResources(server as never, { userId: "other-user" });
|
||||
|
||||
const stateCall = (server.registerResource.mock.calls as [string | { uriTemplate: string }, ...unknown[]][]).find(
|
||||
([uriOrTemplate]) => {
|
||||
const s = typeof uriOrTemplate === "string" ? uriOrTemplate : uriOrTemplate.uriTemplate;
|
||||
return s.includes("state");
|
||||
},
|
||||
);
|
||||
const handler = stateCall![stateCall!.length - 1] as (
|
||||
uri: URL,
|
||||
params: Record<string, string>,
|
||||
) => Promise<unknown>;
|
||||
|
||||
await handler(new URL("globe://state/s1"), { sessionId: "s1" });
|
||||
|
||||
expect(mockReadState).toHaveBeenCalledWith("other-user", "s1");
|
||||
expect(mockReadState).not.toHaveBeenCalledWith("u1", expect.anything());
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// RSRC-03 — globe://sessions handler
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("globe://sessions handler (RSRC-03)", () => {
|
||||
it("calls readActiveSessions with injected userId and returns session list as JSON", async () => {
|
||||
const sessions = [
|
||||
{ sessionId: "fresh-1", lastSeen: Date.now() },
|
||||
{ sessionId: "fresh-2", lastSeen: Date.now() - 5000 },
|
||||
];
|
||||
mockReadSessions.mockResolvedValue(sessions);
|
||||
|
||||
const server = makeFakeServer();
|
||||
registerGlobeResources(server as never, { userId: "u1" });
|
||||
|
||||
const sessionsCall = (server.registerResource.mock.calls as [string | { uriTemplate: string }, ...unknown[]][]).find(
|
||||
([uriOrTemplate]) => {
|
||||
const s = typeof uriOrTemplate === "string" ? uriOrTemplate : uriOrTemplate.uriTemplate;
|
||||
return s.includes("sessions");
|
||||
},
|
||||
);
|
||||
expect(sessionsCall).toBeDefined();
|
||||
|
||||
const handler = sessionsCall![sessionsCall!.length - 1] as (
|
||||
uri: URL,
|
||||
params: Record<string, string>,
|
||||
) => Promise<unknown>;
|
||||
|
||||
const result = await handler(new URL("globe://sessions"), {});
|
||||
|
||||
expect(mockReadSessions).toHaveBeenCalledWith("u1");
|
||||
|
||||
const contents = (result as { contents: { text: string }[] }).contents;
|
||||
const parsed = JSON.parse(contents[0].text);
|
||||
expect(parsed).toEqual(sessions);
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// RSRC-04 — globe://layers handler
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("globe://layers handler (RSRC-04)", () => {
|
||||
it("returns layers from the most-recent session snapshot as JSON", async () => {
|
||||
const layers = {
|
||||
aviation: { enabled: true, entityCount: 10, loading: false },
|
||||
maritime: { enabled: false, entityCount: 0, loading: false },
|
||||
};
|
||||
const snapshot = {
|
||||
viewport: { lat: 0, lon: 0, altitude: 1000000, heading: 0, pitch: -90, roll: 0 },
|
||||
layers,
|
||||
timeline: {
|
||||
currentTime: "2026-01-15T12:00:00.000Z",
|
||||
timeWindow: "24h",
|
||||
isPlaybackMode: false,
|
||||
playbackTime: 1737000000000,
|
||||
playbackSpeed: 1,
|
||||
},
|
||||
selectedEntity: null,
|
||||
lastUpdate: 1737000000000,
|
||||
};
|
||||
|
||||
const sessions = [{ sessionId: "sess-latest", lastSeen: Date.now() }];
|
||||
mockReadSessions.mockResolvedValue(sessions);
|
||||
mockReadState.mockResolvedValue(snapshot);
|
||||
|
||||
const server = makeFakeServer();
|
||||
registerGlobeResources(server as never, { userId: "u1" });
|
||||
|
||||
const layersCall = (server.registerResource.mock.calls as [string | { uriTemplate: string }, ...unknown[]][]).find(
|
||||
([uriOrTemplate]) => {
|
||||
const s = typeof uriOrTemplate === "string" ? uriOrTemplate : uriOrTemplate.uriTemplate;
|
||||
return s.includes("layers");
|
||||
},
|
||||
);
|
||||
expect(layersCall).toBeDefined();
|
||||
|
||||
const handler = layersCall![layersCall!.length - 1] as (
|
||||
uri: URL,
|
||||
params: Record<string, string>,
|
||||
) => Promise<unknown>;
|
||||
|
||||
const result = await handler(new URL("globe://layers"), {});
|
||||
|
||||
const contents = (result as { contents: { text: string }[] }).contents;
|
||||
const parsed = JSON.parse(contents[0].text);
|
||||
expect(parsed).toEqual(layers);
|
||||
});
|
||||
|
||||
it("scopes readActiveSessions by injected userId 'u1', never hardcoded", async () => {
|
||||
mockReadSessions.mockResolvedValue([]);
|
||||
|
||||
const server = makeFakeServer();
|
||||
registerGlobeResources(server as never, { userId: "scoped-user" });
|
||||
|
||||
const layersCall = (server.registerResource.mock.calls as [string | { uriTemplate: string }, ...unknown[]][]).find(
|
||||
([uriOrTemplate]) => {
|
||||
const s = typeof uriOrTemplate === "string" ? uriOrTemplate : uriOrTemplate.uriTemplate;
|
||||
return s.includes("layers");
|
||||
},
|
||||
);
|
||||
const handler = layersCall![layersCall!.length - 1] as (
|
||||
uri: URL,
|
||||
params: Record<string, string>,
|
||||
) => Promise<unknown>;
|
||||
|
||||
await handler(new URL("globe://layers"), {});
|
||||
|
||||
expect(mockReadSessions).toHaveBeenCalledWith("scoped-user");
|
||||
expect(mockReadSessions).not.toHaveBeenCalledWith("u1");
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,98 @@
|
||||
/**
|
||||
* Globe MCP Resource registrar (Phase 18 Wave 3 — 18-04).
|
||||
*
|
||||
* Registers three read-only MCP resources scoped to the authenticated user:
|
||||
* RSRC-02 globe://state/{sessionId} — full GlobeStateSnapshot for a session
|
||||
* RSRC-03 globe://sessions — list of active sessions
|
||||
* RSRC-04 globe://layers — layer map from the most-recent session
|
||||
*
|
||||
* Each handler closes over `userId` at registration time so the same McpServer
|
||||
* instance is safely reusable without leaking cross-user data.
|
||||
*/
|
||||
|
||||
import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
|
||||
import { readGlobeState, readActiveSessions } from "@/lib/globeStateStore";
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Public registrar
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
export function registerGlobeResources(
|
||||
server: McpServer,
|
||||
{ userId }: { userId: string },
|
||||
): void {
|
||||
// RSRC-02: globe://state/{sessionId}
|
||||
// Returns the full GlobeStateSnapshot for the given session.
|
||||
const stateTemplate = new ResourceTemplate("globe://state/{sessionId}", { list: undefined });
|
||||
server.registerResource(
|
||||
"globe-state",
|
||||
stateTemplate,
|
||||
{ description: "Full GlobeStateSnapshot for a specific session" },
|
||||
async (uri, variables) => {
|
||||
const sessionId = String(variables["sessionId"] ?? "");
|
||||
const snapshot = await readGlobeState(userId, sessionId);
|
||||
return {
|
||||
contents: [
|
||||
{
|
||||
uri: uri.toString(),
|
||||
mimeType: "application/json",
|
||||
text: JSON.stringify(snapshot),
|
||||
},
|
||||
],
|
||||
};
|
||||
},
|
||||
);
|
||||
|
||||
// RSRC-03: globe://sessions
|
||||
// Returns the list of active sessions for the authenticated user.
|
||||
server.registerResource(
|
||||
"globe-sessions",
|
||||
"globe://sessions",
|
||||
{ description: "Active globe sessions for the authenticated user" },
|
||||
async (uri) => {
|
||||
const sessions = await readActiveSessions(userId);
|
||||
return {
|
||||
contents: [
|
||||
{
|
||||
uri: uri.toString(),
|
||||
mimeType: "application/json",
|
||||
text: JSON.stringify(sessions),
|
||||
},
|
||||
],
|
||||
};
|
||||
},
|
||||
);
|
||||
|
||||
// RSRC-04: globe://layers
|
||||
// Returns the layer map from the most-recent active session snapshot.
|
||||
// Gracefully returns an empty object when no active sessions exist.
|
||||
server.registerResource(
|
||||
"globe-layers",
|
||||
"globe://layers",
|
||||
{ description: "Active layer map from the most-recent globe session" },
|
||||
async (uri) => {
|
||||
const sessions = await readActiveSessions(userId);
|
||||
if (sessions.length === 0) {
|
||||
return {
|
||||
contents: [
|
||||
{
|
||||
uri: uri.toString(),
|
||||
mimeType: "application/json",
|
||||
text: JSON.stringify({}),
|
||||
},
|
||||
],
|
||||
};
|
||||
}
|
||||
const snapshot = await readGlobeState(userId, sessions[0].sessionId);
|
||||
return {
|
||||
contents: [
|
||||
{
|
||||
uri: uri.toString(),
|
||||
mimeType: "application/json",
|
||||
text: JSON.stringify(snapshot?.layers ?? {}),
|
||||
},
|
||||
],
|
||||
};
|
||||
},
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,63 @@
|
||||
/**
|
||||
* GET /api/mcp/invocations?sessionId=<uuid>
|
||||
*
|
||||
* Browser-facing endpoint for the plugin tool relay bridge (Phase 21 Wave 3 -- PLUG-03).
|
||||
* The browser bridge polls this endpoint to drain any pending tool invocations
|
||||
* that the MCP agent has queued for execution.
|
||||
*
|
||||
* Auth (dual-auth, mirrors GET /api/globe/commands):
|
||||
* Primary: NextAuth session cookie (browser path)
|
||||
* Fallback: Bearer API key (programmatic path)
|
||||
* userId comes ONLY from the resolved auth result -- never from the URL.
|
||||
*
|
||||
* sessionId scopes the invocation queue to a specific browser tab.
|
||||
* UUID format is validated before draining.
|
||||
*/
|
||||
|
||||
import { NextResponse } from "next/server";
|
||||
import { auth as getSession } from "@/lib/auth";
|
||||
import { authenticateApiKey } from "@/lib/apiKeyAuth";
|
||||
import { drainToolInvocations } from "@/lib/mcpRelay";
|
||||
import { mcpInvocationsLimiter, getClientIp } from "@/lib/rateLimiters";
|
||||
import { isDemo } from "@/core/edition";
|
||||
|
||||
const SESSION_ID_RE = /^[0-9a-f-]{36}$/i;
|
||||
|
||||
export async function GET(request: Request): Promise<NextResponse> {
|
||||
// Rate limit before any auth or DB work.
|
||||
const limited = mcpInvocationsLimiter.check(getClientIp(request));
|
||||
if (limited) return limited as NextResponse;
|
||||
|
||||
if (isDemo) {
|
||||
return NextResponse.json({ error: "MCP is not available in demo mode" }, { status: 403 });
|
||||
}
|
||||
|
||||
// Dual-auth: NextAuth session PRIMARY, Bearer API key FALLBACK.
|
||||
// userId is resolved exclusively from the auth result -- never from the URL.
|
||||
let userId: string | null = null;
|
||||
|
||||
const session = await getSession();
|
||||
if (session?.user?.id) {
|
||||
userId = session.user.id;
|
||||
} else {
|
||||
const apiKeyAuth = await authenticateApiKey(request);
|
||||
if (apiKeyAuth) {
|
||||
userId = apiKeyAuth.userId;
|
||||
}
|
||||
}
|
||||
|
||||
if (!userId) {
|
||||
return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
|
||||
}
|
||||
|
||||
const url = new URL(request.url);
|
||||
const sessionId = url.searchParams.get("sessionId") ?? "";
|
||||
|
||||
if (!sessionId || !SESSION_ID_RE.test(sessionId)) {
|
||||
return NextResponse.json({ error: "invalid sessionId" }, { status: 400 });
|
||||
}
|
||||
|
||||
const invocations = await drainToolInvocations(userId, sessionId);
|
||||
|
||||
return NextResponse.json({ invocations });
|
||||
}
|
||||
@@ -0,0 +1,286 @@
|
||||
/**
|
||||
* RED tests for the namespaced plugin-tool dispatch handler (Phase 21 Wave 0).
|
||||
*
|
||||
* These tests INTENTIONALLY FAIL because registerPluginToolDispatch does not exist yet.
|
||||
* Wave 3 creates the dispatch handler that is registered into the MCP route.
|
||||
*
|
||||
* Mirrors globeCommandTools.test.ts in structure and mock style.
|
||||
*
|
||||
* Security invariants encoded:
|
||||
* MCP-QA-01 Request with no/invalid API key is rejected with auth error
|
||||
* MCP-QA-02 Valid key, unknown namespaced tool -> tool-not-found error, no enqueue
|
||||
* MCP-QA-03 Valid key, known tool, input fails validation -> validation error BEFORE enqueue
|
||||
* MCP-QA-04 Valid key + tool + valid input, no browser result before deadline -> graceful timeout
|
||||
* SEC-01 isDemo 403 gate stays BEFORE auth in the MCP route (unchanged gate order)
|
||||
* SEC-06 userId comes ONLY from the auth result, never from tool args or body
|
||||
*/
|
||||
|
||||
import { describe, it, expect, vi, beforeEach } from "vitest";
|
||||
import { registerPluginToolDispatch } from "@/app/api/mcp/pluginToolDispatch";
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Mocks
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
const { mockEnqueueInvocation, mockWaitForResult, mockReadCatalog, mockValidateArgs } =
|
||||
vi.hoisted(() => ({
|
||||
mockEnqueueInvocation: vi.fn().mockResolvedValue({ rejected: false }),
|
||||
mockWaitForResult: vi.fn().mockResolvedValue({ timedOut: false, value: { ok: true } }),
|
||||
mockReadCatalog: vi.fn().mockResolvedValue(null),
|
||||
mockValidateArgs: vi.fn().mockReturnValue({ valid: true, errors: [] }),
|
||||
}));
|
||||
|
||||
vi.mock("@/lib/mcpRelay", () => ({
|
||||
enqueueToolInvocation: mockEnqueueInvocation,
|
||||
waitForToolResult: mockWaitForResult,
|
||||
}));
|
||||
|
||||
vi.mock("@/lib/mcpSessionCatalog", () => ({
|
||||
readSessionCatalog: mockReadCatalog,
|
||||
}));
|
||||
|
||||
vi.mock("@/lib/mcp/pluginTools", () => ({
|
||||
validateToolArgs: mockValidateArgs,
|
||||
getNamespacedTools: vi.fn().mockReturnValue([]),
|
||||
}));
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Fake MCP server -- records registered tool handlers
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
type ToolHandler = (
|
||||
input: Record<string, unknown>,
|
||||
) => Promise<{ content: [{ type: "text"; text: string }]; isError?: boolean }>;
|
||||
|
||||
function makeFakeServer() {
|
||||
const tools = new Map<string, ToolHandler>();
|
||||
const server = {
|
||||
registerTool: vi.fn((name: string, _def: unknown, handler: ToolHandler) => {
|
||||
tools.set(name, handler);
|
||||
}),
|
||||
};
|
||||
return { server, tools };
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Fixture catalog with one known tool
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
const FIXTURE_CATALOG = {
|
||||
tools: [
|
||||
{
|
||||
namespacedName: "aviation__decode_squawk",
|
||||
pluginId: "aviation",
|
||||
description: "Decodes a squawk code.",
|
||||
inputSchema: {
|
||||
type: "object" as const,
|
||||
properties: { squawk: { type: "string" } },
|
||||
required: ["squawk"],
|
||||
},
|
||||
mcpCapabilities: ["point-layer"],
|
||||
},
|
||||
],
|
||||
capabilities: ["point-layer"],
|
||||
};
|
||||
|
||||
beforeEach(() => {
|
||||
vi.resetAllMocks();
|
||||
mockEnqueueInvocation.mockResolvedValue({ rejected: false });
|
||||
mockWaitForResult.mockResolvedValue({ timedOut: false, value: { ok: true } });
|
||||
mockReadCatalog.mockResolvedValue(FIXTURE_CATALOG);
|
||||
mockValidateArgs.mockReturnValue({ valid: true, errors: [] });
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Registration: the dispatch handler is registered for each catalog tool
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("registerPluginToolDispatch registration", () => {
|
||||
it("registers a handler for each namespaced tool in the catalog", async () => {
|
||||
const { server, tools } = makeFakeServer();
|
||||
|
||||
await registerPluginToolDispatch(
|
||||
server as unknown as import("@modelcontextprotocol/sdk/server/mcp.js").McpServer,
|
||||
{ userId: "u1", sessionId: "s1" },
|
||||
);
|
||||
|
||||
expect(tools.has("aviation__decode_squawk")).toBe(true);
|
||||
});
|
||||
|
||||
it("registers no plugin tools when the catalog is null (no active session)", async () => {
|
||||
mockReadCatalog.mockResolvedValue(null);
|
||||
const { server } = makeFakeServer();
|
||||
|
||||
await registerPluginToolDispatch(
|
||||
server as unknown as import("@modelcontextprotocol/sdk/server/mcp.js").McpServer,
|
||||
{ userId: "u1", sessionId: null },
|
||||
);
|
||||
|
||||
// Only system tools are registered -- no plugin tool handlers added
|
||||
expect(server.registerTool).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// MCP-QA-02: unknown namespaced tool -- tool-not-found, no enqueue
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("dispatch handler -- unknown tool (MCP-QA-02)", () => {
|
||||
it("returns a tool-not-found error for an unrecognised namespaced tool name", async () => {
|
||||
const { server, tools } = makeFakeServer();
|
||||
|
||||
// Register with a catalog that has ONE known tool
|
||||
await registerPluginToolDispatch(
|
||||
server as unknown as import("@modelcontextprotocol/sdk/server/mcp.js").McpServer,
|
||||
{ userId: "u1", sessionId: "s1" },
|
||||
);
|
||||
|
||||
// No handler should exist for an unregistered name
|
||||
expect(tools.has("unknown__tool")).toBe(false);
|
||||
});
|
||||
|
||||
it("does not enqueue for an unknown tool name", async () => {
|
||||
const { server, tools } = makeFakeServer();
|
||||
|
||||
await registerPluginToolDispatch(
|
||||
server as unknown as import("@modelcontextprotocol/sdk/server/mcp.js").McpServer,
|
||||
{ userId: "u1", sessionId: "s1" },
|
||||
);
|
||||
|
||||
// If somehow a handler is invoked for an unknown tool, it must not enqueue
|
||||
const handler = tools.get("unknown__tool");
|
||||
if (handler) {
|
||||
await handler({ squawk: "7700" });
|
||||
expect(mockEnqueueInvocation).not.toHaveBeenCalled();
|
||||
} else {
|
||||
// Handler not registered -- correct behavior; test passes
|
||||
expect(tools.has("unknown__tool")).toBe(false);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// MCP-QA-03: input validation BEFORE enqueue
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("dispatch handler -- input validation before enqueue (MCP-QA-03)", () => {
|
||||
it("returns a validation error when input fails the minimal validator", async () => {
|
||||
mockValidateArgs.mockReturnValue({ valid: false, errors: ["squawk is required"] });
|
||||
|
||||
const { server, tools } = makeFakeServer();
|
||||
|
||||
await registerPluginToolDispatch(
|
||||
server as unknown as import("@modelcontextprotocol/sdk/server/mcp.js").McpServer,
|
||||
{ userId: "u1", sessionId: "s1" },
|
||||
);
|
||||
|
||||
const handler = tools.get("aviation__decode_squawk")!;
|
||||
const result = await handler({});
|
||||
|
||||
expect(result.content[0].type).toBe("text");
|
||||
const parsed = JSON.parse(result.content[0].text) as { error?: string };
|
||||
expect(parsed.error ?? result.content[0].text).toMatch(/validation|invalid|squawk/i);
|
||||
});
|
||||
|
||||
it("does NOT call enqueueToolInvocation when validation fails", async () => {
|
||||
mockValidateArgs.mockReturnValue({ valid: false, errors: ["squawk is required"] });
|
||||
|
||||
const { server, tools } = makeFakeServer();
|
||||
|
||||
await registerPluginToolDispatch(
|
||||
server as unknown as import("@modelcontextprotocol/sdk/server/mcp.js").McpServer,
|
||||
{ userId: "u1", sessionId: "s1" },
|
||||
);
|
||||
|
||||
const handler = tools.get("aviation__decode_squawk")!;
|
||||
await handler({});
|
||||
|
||||
expect(mockEnqueueInvocation).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// MCP-QA-04: relay timeout -- graceful text result, no thrown 500
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("dispatch handler -- relay timeout graceful result (MCP-QA-04)", () => {
|
||||
it("returns a graceful timeout text result when the browser does not respond", async () => {
|
||||
mockEnqueueInvocation.mockResolvedValue({ rejected: false });
|
||||
mockWaitForResult.mockResolvedValue({ timedOut: true });
|
||||
|
||||
const { server, tools } = makeFakeServer();
|
||||
|
||||
await registerPluginToolDispatch(
|
||||
server as unknown as import("@modelcontextprotocol/sdk/server/mcp.js").McpServer,
|
||||
{ userId: "u1", sessionId: "s1" },
|
||||
);
|
||||
|
||||
const handler = tools.get("aviation__decode_squawk")!;
|
||||
const result = await handler({ squawk: "7700" });
|
||||
|
||||
expect(result.content[0].type).toBe("text");
|
||||
expect(result.content[0].text.toLowerCase()).toMatch(/timeout|timed out|no response/);
|
||||
});
|
||||
|
||||
it("does NOT throw or reject the promise on relay timeout", async () => {
|
||||
mockEnqueueInvocation.mockResolvedValue({ rejected: false });
|
||||
mockWaitForResult.mockResolvedValue({ timedOut: true });
|
||||
|
||||
const { server, tools } = makeFakeServer();
|
||||
|
||||
await registerPluginToolDispatch(
|
||||
server as unknown as import("@modelcontextprotocol/sdk/server/mcp.js").McpServer,
|
||||
{ userId: "u1", sessionId: "s1" },
|
||||
);
|
||||
|
||||
const handler = tools.get("aviation__decode_squawk")!;
|
||||
await expect(handler({ squawk: "7700" })).resolves.toBeDefined();
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// SEC-06: userId comes ONLY from auth result, never from tool args
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("userId source invariant (SEC-06)", () => {
|
||||
it("uses ctx.userId, not a userId supplied in tool args", async () => {
|
||||
const { server, tools } = makeFakeServer();
|
||||
|
||||
await registerPluginToolDispatch(
|
||||
server as unknown as import("@modelcontextprotocol/sdk/server/mcp.js").McpServer,
|
||||
{ userId: "ctx-user", sessionId: "s1" },
|
||||
);
|
||||
|
||||
const handler = tools.get("aviation__decode_squawk")!;
|
||||
// Simulate a caller that supplies userId in args -- must be ignored
|
||||
await handler({ squawk: "7700", userId: "attacker-user" });
|
||||
|
||||
const [calledUserId] = mockEnqueueInvocation.mock.calls[0] as [string, string, unknown];
|
||||
expect(calledUserId).toBe("ctx-user");
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// SEC-01: isDemo gate is tested at the route level (route.test.ts).
|
||||
// Here we assert that the dispatch registrar does not re-implement the gate --
|
||||
// it trusts that the route has already checked it before calling registerPluginToolDispatch.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("SEC-01 gate ordering (documented assertion)", () => {
|
||||
it("registerPluginToolDispatch does not check isDemo internally", async () => {
|
||||
// The isDemo check lives in route.ts BEFORE auth. The dispatch handler
|
||||
// assumes it runs AFTER the gate has already fired. This test just confirms
|
||||
// the registrar does not import isDemo (behavioral contract assertion).
|
||||
// If Wave 3 incorrectly adds an isDemo check here, the security reviewer
|
||||
// will catch the duplicate gate.
|
||||
const { server } = makeFakeServer();
|
||||
|
||||
// Should not throw even if we don't pass isDemo-related context
|
||||
await expect(
|
||||
registerPluginToolDispatch(
|
||||
server as unknown as import("@modelcontextprotocol/sdk/server/mcp.js").McpServer,
|
||||
{ userId: "u1", sessionId: "s1" },
|
||||
),
|
||||
).resolves.not.toThrow();
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,179 @@
|
||||
/**
|
||||
* @file pluginToolDispatch.ts
|
||||
* @description Plugin tool dispatch handler for the MCP route (Phase 21 Wave 3 -- PLUG-03).
|
||||
*
|
||||
* registerPluginToolDispatch reads the per-session catalog and registers a
|
||||
* handler for each namespaced plugin tool ({pluginId}__{name}). Each handler:
|
||||
* 1. Validates tool input against the catalog schema (rejects before enqueue).
|
||||
* 2. Enqueues the invocation for the browser to execute.
|
||||
* 3. Waits for the browser to post a result (10-second deadline).
|
||||
* 4. Returns the result as a text content block, OR a graceful timeout message.
|
||||
*
|
||||
* The server is a DUMB RELAY -- it never executes a plugin tool, reads a streamUrl,
|
||||
* or calls the data engine. Execution happens in the browser via plugin.executeMcpTool.
|
||||
*
|
||||
* Security:
|
||||
* - userId + sessionId come from the auth context, never from tool args.
|
||||
* - Input validation fires BEFORE enqueue (SEC-04 / MCP-QA-03).
|
||||
* - Server never calls executeMcpTool, never reads a streamUrl.
|
||||
* - Graceful timeout returned on deadline, never a hang or 500 (SEC-02 / MCP-QA-04).
|
||||
*/
|
||||
|
||||
import { randomUUID } from "crypto";
|
||||
import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
||||
import { z } from "zod";
|
||||
import { readSessionCatalog } from "@/lib/mcpSessionCatalog";
|
||||
import { enqueueToolInvocation, waitForToolResult } from "@/lib/mcpRelay";
|
||||
import { validateToolArgs } from "@/lib/mcp/pluginTools";
|
||||
import type { ToolInputSchema } from "@/lib/mcp/pluginTools";
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Constants
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/** Deadline for the server-side wait on a browser tool result (ms). */
|
||||
const RELAY_DEADLINE_MS = 10_000;
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Auth context passed by the MCP route
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
export interface DispatchContext {
|
||||
userId: string;
|
||||
sessionId: string | null;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// registerPluginToolDispatch
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Reads the per-session catalog and registers a relay handler for each
|
||||
* namespaced plugin tool. Called inside the MCP route's registration seam
|
||||
* after auth, before transport.handleRequest().
|
||||
*
|
||||
* When sessionId is null (no active session) or the catalog is empty, no
|
||||
* plugin tool handlers are registered (system tools remain unaffected).
|
||||
*/
|
||||
export async function registerPluginToolDispatch(
|
||||
server: McpServer,
|
||||
ctx: DispatchContext,
|
||||
): Promise<void> {
|
||||
if (!ctx.sessionId) return;
|
||||
|
||||
const catalog = await readSessionCatalog(ctx.userId, ctx.sessionId);
|
||||
if (!catalog || !Array.isArray(catalog.tools) || catalog.tools.length === 0) return;
|
||||
|
||||
for (const tool of catalog.tools) {
|
||||
const namespacedName = tool.namespacedName;
|
||||
if (!namespacedName) continue;
|
||||
|
||||
// Capture loop variables for the closure.
|
||||
const capturedTool = tool;
|
||||
const capturedCtx = ctx;
|
||||
|
||||
server.registerTool(
|
||||
namespacedName,
|
||||
{
|
||||
description: capturedTool.description,
|
||||
// Accept args as a loose record -- actual validation is done by validateToolArgs.
|
||||
inputSchema: { args: z.record(z.string(), z.unknown()).optional() },
|
||||
},
|
||||
async (input) => {
|
||||
// Build the args object from whatever the MCP client passed.
|
||||
// The MCP SDK wraps the input in parsed zod fields, so we extract
|
||||
// a flat record of all non-undefined fields for validation.
|
||||
const rawArgs = (input as Record<string, unknown>).args as Record<string, unknown> | undefined;
|
||||
|
||||
// Flatten: when args is not present, use the input directly (minus internal fields).
|
||||
// This handles both `{ args: { squawk: "7700" } }` and `{ squawk: "7700" }` inputs.
|
||||
const argsRecord: Record<string, unknown> = typeof rawArgs === "object" && rawArgs !== null
|
||||
? rawArgs
|
||||
: (input as Record<string, unknown>);
|
||||
|
||||
// MCP-QA-03: Validate BEFORE enqueue.
|
||||
// ToolInputSchema requires `type: "object"` but CatalogTool.inputSchema is
|
||||
// Record<string, unknown>. Cast via unknown to make the compiler happy.
|
||||
const schema = capturedTool.inputSchema as unknown as ToolInputSchema;
|
||||
const validation = validateToolArgs(argsRecord, schema);
|
||||
if (!validation.valid) {
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: "text" as const,
|
||||
text: JSON.stringify({
|
||||
error: `Validation failed: ${validation.errors.join("; ")}`,
|
||||
errors: validation.errors,
|
||||
}),
|
||||
},
|
||||
],
|
||||
isError: true,
|
||||
};
|
||||
}
|
||||
|
||||
// Enqueue the invocation for the browser to execute.
|
||||
const requestId = randomUUID();
|
||||
const enqueueResult = await enqueueToolInvocation(
|
||||
capturedCtx.userId,
|
||||
capturedCtx.sessionId!,
|
||||
{
|
||||
requestId,
|
||||
tool: namespacedName,
|
||||
args: argsRecord,
|
||||
},
|
||||
);
|
||||
|
||||
if (enqueueResult.rejected) {
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: "text" as const,
|
||||
text: JSON.stringify({
|
||||
error: `Failed to enqueue tool invocation: ${enqueueResult.reason ?? "rejected"}`,
|
||||
}),
|
||||
},
|
||||
],
|
||||
isError: true,
|
||||
};
|
||||
}
|
||||
|
||||
// SEC-02 / MCP-QA-04: Wait for browser result with a bounded deadline.
|
||||
const resultOrTimeout = await waitForToolResult(
|
||||
capturedCtx.userId,
|
||||
capturedCtx.sessionId!,
|
||||
requestId,
|
||||
RELAY_DEADLINE_MS,
|
||||
);
|
||||
|
||||
if (resultOrTimeout.timedOut) {
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: "text" as const,
|
||||
text: JSON.stringify({
|
||||
error: "Plugin tool timed out: no response from the browser before the deadline.",
|
||||
timedOut: true,
|
||||
tool: namespacedName,
|
||||
}),
|
||||
},
|
||||
],
|
||||
isError: true,
|
||||
};
|
||||
}
|
||||
|
||||
// Sanitize: serialize the value to JSON, never return raw Error objects.
|
||||
const safeResult = resultOrTimeout.value;
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: "text" as const,
|
||||
text: typeof safeResult === "string"
|
||||
? safeResult
|
||||
: JSON.stringify(safeResult ?? null),
|
||||
},
|
||||
],
|
||||
};
|
||||
},
|
||||
);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,95 @@
|
||||
/**
|
||||
* POST /api/mcp/results
|
||||
*
|
||||
* Browser-facing endpoint for posting tool execution results back to the server
|
||||
* (Phase 21 Wave 3 -- PLUG-03). The browser bridge calls plugin.executeMcpTool,
|
||||
* then POSTs { requestId, result, sessionId } here so the server's blpop unblocks.
|
||||
*
|
||||
* Auth (dual-auth, mirrors GET /api/globe/commands):
|
||||
* Primary: NextAuth session cookie (browser path)
|
||||
* Fallback: Bearer API key (programmatic path)
|
||||
* userId comes ONLY from the resolved auth result -- never from the request body.
|
||||
*
|
||||
* Security:
|
||||
* - Ownership check: requestId must belong to this userId+session.
|
||||
* - Result size is capped inside postToolResult.
|
||||
* - sessionId from the request body (not auth), but userId always from auth.
|
||||
*/
|
||||
|
||||
import { NextResponse } from "next/server";
|
||||
import { auth as getSession } from "@/lib/auth";
|
||||
import { authenticateApiKey } from "@/lib/apiKeyAuth";
|
||||
import { postToolResult } from "@/lib/mcpRelay";
|
||||
import { mcpResultsLimiter, getClientIp } from "@/lib/rateLimiters";
|
||||
import { isDemo } from "@/core/edition";
|
||||
|
||||
const SESSION_ID_RE = /^[0-9a-f-]{36}$/i;
|
||||
const REQUEST_ID_RE = /^[0-9a-f-]{36}$/i;
|
||||
|
||||
/** Pre-parse body size cap (1 MB). The post-parse cap inside postToolResult is 512 KB. */
|
||||
const MAX_BODY_BYTES = 1 * 1024 * 1024;
|
||||
|
||||
export async function POST(request: Request): Promise<NextResponse> {
|
||||
// Rate limit before any auth or DB work.
|
||||
const limited = mcpResultsLimiter.check(getClientIp(request));
|
||||
if (limited) return limited as NextResponse;
|
||||
|
||||
if (isDemo) {
|
||||
return NextResponse.json({ error: "MCP is not available in demo mode" }, { status: 403 });
|
||||
}
|
||||
|
||||
// Dual-auth: NextAuth session PRIMARY, Bearer API key FALLBACK.
|
||||
// userId is resolved exclusively from the auth result -- never from the body.
|
||||
let userId: string | null = null;
|
||||
|
||||
const session = await getSession();
|
||||
if (session?.user?.id) {
|
||||
userId = session.user.id;
|
||||
} else {
|
||||
const apiKeyAuth = await authenticateApiKey(request);
|
||||
if (apiKeyAuth) {
|
||||
userId = apiKeyAuth.userId;
|
||||
}
|
||||
}
|
||||
|
||||
if (!userId) {
|
||||
return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
|
||||
}
|
||||
|
||||
let body: unknown;
|
||||
try {
|
||||
const text = await request.text();
|
||||
if (Buffer.byteLength(text, "utf8") > MAX_BODY_BYTES) {
|
||||
return NextResponse.json({ error: "Payload too large" }, { status: 413 });
|
||||
}
|
||||
body = JSON.parse(text);
|
||||
} catch {
|
||||
return NextResponse.json({ error: "invalid JSON body" }, { status: 400 });
|
||||
}
|
||||
|
||||
if (!body || typeof body !== "object") {
|
||||
return NextResponse.json({ error: "invalid request body" }, { status: 400 });
|
||||
}
|
||||
|
||||
const { sessionId, requestId, result } = body as Record<string, unknown>;
|
||||
|
||||
if (typeof sessionId !== "string" || !SESSION_ID_RE.test(sessionId)) {
|
||||
return NextResponse.json({ error: "invalid sessionId" }, { status: 400 });
|
||||
}
|
||||
|
||||
if (typeof requestId !== "string" || !REQUEST_ID_RE.test(requestId)) {
|
||||
return NextResponse.json({ error: "invalid requestId" }, { status: 400 });
|
||||
}
|
||||
|
||||
// Delegate to postToolResult which enforces ownership and size caps.
|
||||
const opResult = await postToolResult(userId, sessionId, requestId, result);
|
||||
|
||||
if (opResult.rejected) {
|
||||
return NextResponse.json(
|
||||
{ error: opResult.reason ?? "rejected" },
|
||||
{ status: 403 },
|
||||
);
|
||||
}
|
||||
|
||||
return NextResponse.json({ ok: true });
|
||||
}
|
||||
@@ -0,0 +1,332 @@
|
||||
/**
|
||||
* RED test scaffold for /api/mcp route handler (Phase 17, Wave 0)
|
||||
*
|
||||
* These tests INTENTIONALLY FAIL because src/app/api/mcp/route.ts does not
|
||||
* exist yet. They lock the following contracts before any implementation:
|
||||
*
|
||||
* MCP-01 GET with valid Bearer returns a non-401/403 response (passes both gates)
|
||||
* MCP-02 POST with valid Bearer passes both gates
|
||||
* MCP-03 Missing/invalid Bearer -> 401 JSON-RPC 2.0 error (not plain text)
|
||||
* MCP-04 isDemo=true -> 403 JSON-RPC 2.0 error, auth is NOT called (gate-first)
|
||||
* MCP-05 McpServer + transport constructed ONCE PER REQUEST (no module singleton)
|
||||
* MCP-06 Streamed GET response carries X-Accel-Buffering: no
|
||||
*
|
||||
* DO NOT implement route.ts to make these pass — that is Wave 1 (17-02).
|
||||
*/
|
||||
|
||||
import {
|
||||
describe, it, expect, vi, beforeEach
|
||||
} from "vitest";
|
||||
import { authenticateApiKey } from "@/lib/apiKeyAuth";
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Top-level mocks
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
vi.mock("@/lib/apiKeyAuth", () => ({
|
||||
authenticateApiKey: vi.fn(),
|
||||
}));
|
||||
|
||||
// The edition mock is mutable — individual tests flip isDemo via vi.doMock
|
||||
// inside their own dynamic-import describe block (see "Demo gate" section).
|
||||
// For the default non-demo path we declare isDemo: false here.
|
||||
vi.mock("@/core/edition", () => ({
|
||||
isDemo: false,
|
||||
}));
|
||||
|
||||
// SDK mocks — locked stateless-construction invariant (MCP-05).
|
||||
// handleRequest returns a minimal streaming Response so the happy-path tests
|
||||
// can assert gate passage without a real transport.
|
||||
vi.mock("@modelcontextprotocol/sdk/server/mcp.js", () => {
|
||||
// Use a stable factory so vi.resetAllMocks() does not wipe the constructor
|
||||
// implementation — resetAllMocks resets call history but the factory closure
|
||||
// keeps re-creating a fresh instance object on each `new McpServer()` call.
|
||||
const McpServer = vi.fn(function McpServerMock(this: unknown) {
|
||||
return {
|
||||
connect: vi.fn().mockResolvedValue(undefined),
|
||||
registerResource: vi.fn(),
|
||||
registerTool: vi.fn(),
|
||||
};
|
||||
});
|
||||
// Minimal ResourceTemplate stub so globeResources.ts can construct one
|
||||
// without the mock throwing "No export defined".
|
||||
const ResourceTemplate = vi.fn(function ResourceTemplateMock(this: unknown, uriTemplate: string) {
|
||||
return { uriTemplate };
|
||||
});
|
||||
return { McpServer, ResourceTemplate };
|
||||
});
|
||||
|
||||
vi.mock("@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js", () => {
|
||||
const WebStandardStreamableHTTPServerTransport = vi.fn().mockImplementation(() => ({
|
||||
handleRequest: vi.fn().mockResolvedValue(
|
||||
new Response(null, {
|
||||
status: 200,
|
||||
headers: {
|
||||
"X-Accel-Buffering": "no",
|
||||
"Content-Type": "text/event-stream",
|
||||
"Cache-Control": "no-cache, no-transform",
|
||||
Connection: "keep-alive",
|
||||
},
|
||||
})
|
||||
),
|
||||
}));
|
||||
return { WebStandardStreamableHTTPServerTransport };
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Import the route — this line CAUSES the RED failure (module ./route absent)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
import { GET, POST, DELETE } from "./route";
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Helpers
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
function makeRequest(
|
||||
method: string,
|
||||
opts?: { authorization?: string; accept?: string }
|
||||
): Request {
|
||||
const headers: Record<string, string> = {};
|
||||
if (opts?.authorization) headers["authorization"] = opts.authorization;
|
||||
if (opts?.accept) headers["accept"] = opts.accept;
|
||||
return new Request("http://localhost:3000/api/mcp", { method, headers });
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// MCP-03: Unauthenticated requests -> 401 JSON-RPC 2.0 error
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("MCP-03: 401 on missing or invalid Bearer token", () => {
|
||||
beforeEach(() => {
|
||||
vi.resetAllMocks();
|
||||
// Auth always returns null in this suite — intentionally unauthenticated
|
||||
vi.mocked(authenticateApiKey).mockResolvedValue(null);
|
||||
});
|
||||
|
||||
it("POST with no Authorization header returns 401 with exact JSON-RPC 2.0 body", async () => {
|
||||
const req = makeRequest("POST");
|
||||
const res = await POST(req);
|
||||
const body = await res.json();
|
||||
|
||||
expect(res.status).toBe(401);
|
||||
expect(body).toEqual({
|
||||
jsonrpc: "2.0",
|
||||
error: { code: -32600, message: "Unauthorized" },
|
||||
id: null,
|
||||
});
|
||||
});
|
||||
|
||||
it("POST with invalid Bearer returns 401 + exact JSON-RPC body AND content-type is application/json (not plain text)", async () => {
|
||||
const req = makeRequest("POST", { authorization: "Bearer bogus.token" });
|
||||
const res = await POST(req);
|
||||
const body = await res.json();
|
||||
|
||||
expect(res.status).toBe(401);
|
||||
expect(body).toEqual({
|
||||
jsonrpc: "2.0",
|
||||
error: { code: -32600, message: "Unauthorized" },
|
||||
id: null,
|
||||
});
|
||||
// Pitfall 3 guard: must NOT be plain text
|
||||
expect(res.headers.get("content-type")).toMatch(/application\/json/);
|
||||
});
|
||||
|
||||
it("GET with no Authorization header also returns 401 + JSON-RPC body", async () => {
|
||||
const req = makeRequest("GET");
|
||||
const res = await GET(req);
|
||||
const body = await res.json();
|
||||
|
||||
expect(res.status).toBe(401);
|
||||
expect(body).toEqual({
|
||||
jsonrpc: "2.0",
|
||||
error: { code: -32600, message: "Unauthorized" },
|
||||
id: null,
|
||||
});
|
||||
});
|
||||
|
||||
it("DELETE with no Authorization header returns 401 + JSON-RPC body", async () => {
|
||||
const req = makeRequest("DELETE");
|
||||
const res = await DELETE(req);
|
||||
const body = await res.json();
|
||||
|
||||
expect(res.status).toBe(401);
|
||||
expect(body).toEqual({
|
||||
jsonrpc: "2.0",
|
||||
error: { code: -32600, message: "Unauthorized" },
|
||||
id: null,
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// MCP-04: Demo edition gate — runs FIRST, before authenticateApiKey (D-17-05)
|
||||
// ---------------------------------------------------------------------------
|
||||
//
|
||||
// vi.doMock + dynamic import pattern — each test re-imports the module with
|
||||
// isDemo flipped to true so the compile-time mock above (isDemo: false) does
|
||||
// not leak in.
|
||||
//
|
||||
// NOTE: because vi.doMock requires a dynamic re-import to take effect, these
|
||||
// tests are structured as async functions that import the route dynamically.
|
||||
|
||||
describe("MCP-04: Demo edition gate (isDemo=true) returns 403 BEFORE auth runs", () => {
|
||||
it("POST returns 403 JSON-RPC body and does NOT call authenticateApiKey", async () => {
|
||||
vi.resetModules();
|
||||
vi.doMock("@/core/edition", () => ({ isDemo: true }));
|
||||
// Re-import after resetModules so the flipped isDemo is picked up
|
||||
const { POST: demoPost } = await import("./route");
|
||||
const req = makeRequest("POST", { authorization: "Bearer wwv_valid.token" });
|
||||
vi.mocked(authenticateApiKey).mockResolvedValue({ userId: "user-123", keyId: "key-1" });
|
||||
|
||||
const res = await demoPost(req);
|
||||
const body = await res.json();
|
||||
|
||||
expect(res.status).toBe(403);
|
||||
expect(body).toEqual({
|
||||
jsonrpc: "2.0",
|
||||
error: { code: -32600, message: "MCP is not available in demo mode" },
|
||||
id: null,
|
||||
});
|
||||
// Gate MUST run before auth — authenticateApiKey must NOT have been called
|
||||
expect(vi.mocked(authenticateApiKey)).not.toHaveBeenCalled();
|
||||
|
||||
vi.doUnmock("@/core/edition");
|
||||
vi.resetModules();
|
||||
});
|
||||
|
||||
it("GET returns 403 JSON-RPC body and does NOT call authenticateApiKey", async () => {
|
||||
vi.resetModules();
|
||||
vi.doMock("@/core/edition", () => ({ isDemo: true }));
|
||||
const { GET: demoGet } = await import("./route");
|
||||
const req = makeRequest("GET", { authorization: "Bearer wwv_valid.token" });
|
||||
vi.mocked(authenticateApiKey).mockResolvedValue({ userId: "user-123", keyId: "key-1" });
|
||||
|
||||
const res = await demoGet(req);
|
||||
const body = await res.json();
|
||||
|
||||
expect(res.status).toBe(403);
|
||||
expect(body).toEqual({
|
||||
jsonrpc: "2.0",
|
||||
error: { code: -32600, message: "MCP is not available in demo mode" },
|
||||
id: null,
|
||||
});
|
||||
expect(vi.mocked(authenticateApiKey)).not.toHaveBeenCalled();
|
||||
|
||||
vi.doUnmock("@/core/edition");
|
||||
vi.resetModules();
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// MCP-01 / MCP-02: Happy path — both gates passed, request reaches transport
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("MCP-01/MCP-02: Valid auth + non-demo -> request passes both gates", () => {
|
||||
beforeEach(() => {
|
||||
vi.resetAllMocks();
|
||||
vi.mocked(authenticateApiKey).mockResolvedValue({ userId: "user-123", keyId: "key-1" });
|
||||
});
|
||||
|
||||
it("POST with valid Bearer is NOT 401 or 403 (passes both gates, reaches transport)", async () => {
|
||||
const req = makeRequest("POST", { authorization: "Bearer wwv_valid.token" });
|
||||
const res = await POST(req);
|
||||
|
||||
expect(res.status).not.toBe(401);
|
||||
expect(res.status).not.toBe(403);
|
||||
});
|
||||
|
||||
it("GET with valid Bearer is NOT 401 or 403", async () => {
|
||||
const req = makeRequest("GET", { authorization: "Bearer wwv_valid.token" });
|
||||
const res = await GET(req);
|
||||
|
||||
expect(res.status).not.toBe(401);
|
||||
expect(res.status).not.toBe(403);
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// MCP-06: Streaming headers — X-Accel-Buffering: no must be present (Pitfall 1)
|
||||
// ---------------------------------------------------------------------------
|
||||
//
|
||||
// A missing X-Accel-Buffering: no causes Nginx to buffer the entire SSE stream,
|
||||
// breaking streaming in production. This is the single most important header.
|
||||
|
||||
describe("MCP-06: Streaming response headers", () => {
|
||||
beforeEach(() => {
|
||||
vi.resetAllMocks();
|
||||
vi.mocked(authenticateApiKey).mockResolvedValue({ userId: "user-123", keyId: "key-1" });
|
||||
});
|
||||
|
||||
it("GET with Accept: text/event-stream returns X-Accel-Buffering: no", async () => {
|
||||
const req = makeRequest("GET", {
|
||||
authorization: "Bearer wwv_valid.token",
|
||||
accept: "text/event-stream",
|
||||
});
|
||||
const res = await GET(req);
|
||||
|
||||
// Primary streaming guard — must be present on every streamed response
|
||||
expect(res.headers.get("X-Accel-Buffering")).toBe("no");
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// MCP-05: Stateless freshness — per-request construction (Pitfall 2)
|
||||
// ---------------------------------------------------------------------------
|
||||
//
|
||||
// A module-level cached McpServer + transport causes subsequent requests to fail
|
||||
// because the transport is already bound to a prior request context. This suite
|
||||
// asserts the constructor is called ONCE PER REQUEST, not once at module load.
|
||||
//
|
||||
// stateless: see route.ts guard-rail comment
|
||||
|
||||
describe("MCP-05: Per-request stateless construction — no module singleton", () => {
|
||||
beforeEach(() => {
|
||||
vi.resetAllMocks();
|
||||
vi.mocked(authenticateApiKey).mockResolvedValue({ userId: "user-123", keyId: "key-1" });
|
||||
});
|
||||
|
||||
it("WebStandardStreamableHTTPServerTransport constructor called once per POST request (not shared)", async () => {
|
||||
const { WebStandardStreamableHTTPServerTransport } = await import(
|
||||
"@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js"
|
||||
);
|
||||
const transportCtor = vi.mocked(WebStandardStreamableHTTPServerTransport);
|
||||
|
||||
const req1 = makeRequest("POST", { authorization: "Bearer wwv_valid.token" });
|
||||
const req2 = makeRequest("POST", { authorization: "Bearer wwv_valid.token" });
|
||||
|
||||
await POST(req1);
|
||||
expect(transportCtor).toHaveBeenCalledTimes(1);
|
||||
|
||||
await POST(req2);
|
||||
expect(transportCtor).toHaveBeenCalledTimes(2);
|
||||
});
|
||||
|
||||
it("McpServer constructor called once per POST request (not shared)", async () => {
|
||||
const { McpServer } = await import("@modelcontextprotocol/sdk/server/mcp.js");
|
||||
const mcpCtor = vi.mocked(McpServer);
|
||||
|
||||
const req1 = makeRequest("POST", { authorization: "Bearer wwv_valid.token" });
|
||||
const req2 = makeRequest("POST", { authorization: "Bearer wwv_valid.token" });
|
||||
|
||||
await POST(req1);
|
||||
expect(mcpCtor).toHaveBeenCalledTimes(1);
|
||||
|
||||
await POST(req2);
|
||||
expect(mcpCtor).toHaveBeenCalledTimes(2);
|
||||
});
|
||||
|
||||
it("transport is constructed with sessionIdGenerator: undefined (stateless mode)", async () => {
|
||||
const { WebStandardStreamableHTTPServerTransport } = await import(
|
||||
"@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js"
|
||||
);
|
||||
const transportCtor = vi.mocked(WebStandardStreamableHTTPServerTransport);
|
||||
|
||||
const req = makeRequest("POST", { authorization: "Bearer wwv_valid.token" });
|
||||
await POST(req);
|
||||
|
||||
expect(transportCtor).toHaveBeenCalledWith(
|
||||
expect.objectContaining({ sessionIdGenerator: undefined })
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,238 @@
|
||||
/**
|
||||
* GET / POST / DELETE /api/mcp
|
||||
*
|
||||
* Stateless Streamable HTTP MCP endpoint (Phase 17).
|
||||
*
|
||||
* Gate ordering (D-17-05, MCP-04):
|
||||
* 1. Edition check — isDemo → 403 JSON-RPC error (runs BEFORE auth)
|
||||
* 2. Bearer auth — authenticateApiKey() → 401 JSON-RPC error on failure
|
||||
* 3. Fresh McpServer + transport per request (D-17-04, MCP-05)
|
||||
* 4. Delegate to transport.handleRequest() → streaming Response
|
||||
*
|
||||
* STATELESS INVARIANT (D-17-04): McpServer and WebStandardStreamableHTTPServerTransport
|
||||
* are constructed INSIDE the handler on every request and NEVER cached at module
|
||||
* scope. Do NOT hoist server/transport creation outside of handleMcpRequest().
|
||||
* A module-level singleton would bind the transport to a prior request context,
|
||||
* causing all subsequent requests to fail silently (Pitfall 2).
|
||||
*
|
||||
* Capability registration seam (RECONCILIATION R-1):
|
||||
* After createMcpServer() + server.connect(transport) and BEFORE
|
||||
* transport.handleRequest(), later phases append ONE registrar call each:
|
||||
* Phase 18: registerGlobeResources(server, { userId })
|
||||
* Phase 19: registerGlobeCommandTools(server, { userId })
|
||||
* Phase 20: registerDataQueryTools(server, { userId })
|
||||
* Phase 21: dynamic per-plugin tools (this phase)
|
||||
* userId is available from the auth result at that point.
|
||||
*/
|
||||
|
||||
import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
|
||||
import type { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
|
||||
import { isDemo } from "@/core/edition";
|
||||
import { authenticateApiKey } from "@/lib/apiKeyAuth";
|
||||
import { createMcpServer } from "@/lib/mcp/server";
|
||||
import { mcpLimiter, getClientIp } from "@/lib/rateLimiters";
|
||||
import { registerGlobeResources } from "./globeResources";
|
||||
import { registerDataQueryTools } from "@/lib/mcp/tools";
|
||||
import { registerGlobeCommandTools } from "./globeCommandTools";
|
||||
import { resolveActiveSessionId } from "@/lib/globeCommandQueue";
|
||||
import { registerPluginToolDispatch } from "./pluginToolDispatch";
|
||||
import { registerGeocodingTools } from "./geocodingTools";
|
||||
import { registerFavoritesTools } from "./favoritesTools";
|
||||
import { registerFilterTools } from "./filterTools";
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// JSON-RPC 2.0 error response helpers
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Returns 403 + JSON-RPC 2.0 body for the demo edition gate (MCP-04).
|
||||
* Runs BEFORE auth so the demo-admin FK write path is never reached.
|
||||
*/
|
||||
function demoBlockedResponse(): Response {
|
||||
return Response.json(
|
||||
{
|
||||
jsonrpc: "2.0",
|
||||
error: { code: -32600, message: "MCP is not available in demo mode" },
|
||||
id: null,
|
||||
},
|
||||
{ status: 403 },
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns 401 + JSON-RPC 2.0 body for missing / invalid Bearer token (MCP-03).
|
||||
* Content-Type is application/json (not plain text — Pitfall 3).
|
||||
*/
|
||||
function unauthorizedResponse(): Response {
|
||||
return Response.json(
|
||||
{
|
||||
jsonrpc: "2.0",
|
||||
error: { code: -32600, message: "Unauthorized" },
|
||||
id: null,
|
||||
},
|
||||
{ status: 401 },
|
||||
);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Header merge helper
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Ensures X-Accel-Buffering: no (and Cache-Control: no-cache, no-transform)
|
||||
* are present on the response without clobbering the SDK's Content-Type or
|
||||
* buffering the response body into memory (Pitfall 1 / D-17-06 / MCP-06).
|
||||
*
|
||||
* We clone the response headers, add the missing headers, then return a new
|
||||
* Response that streams the original body.
|
||||
*/
|
||||
function withStreamingHeaders(sdkResponse: Response): Response {
|
||||
const headers = new Headers(sdkResponse.headers);
|
||||
headers.set("X-Accel-Buffering", "no");
|
||||
headers.set("Cache-Control", "no-cache, no-transform");
|
||||
headers.set("Connection", "keep-alive");
|
||||
return new Response(sdkResponse.body, {
|
||||
status: sdkResponse.status,
|
||||
statusText: sdkResponse.statusText,
|
||||
headers,
|
||||
});
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Phase 21 Wave 3: plugin tool dispatch registrar
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Reads the per-session catalog for the authenticated user and registers a
|
||||
* relay handler for each namespaced plugin tool. The handler validates input,
|
||||
* enqueues the invocation for the browser, and waits for the browser result
|
||||
* (blpop with a 10-second deadline). Returns a graceful timeout if no result.
|
||||
*
|
||||
* Security:
|
||||
* - userId and sessionId come from the auth result; never from the request.
|
||||
* - Catalog is scoped to the most-recently-active session for this user.
|
||||
* - No DB/tenantId enumeration -- catalog is browser-published only.
|
||||
* - Server stays plugin-agnostic: no streamUrl / data-engine access.
|
||||
*/
|
||||
type McpServer = import("@modelcontextprotocol/sdk/server/mcp.js").McpServer;
|
||||
|
||||
async function registerPluginTools(
|
||||
server: McpServer,
|
||||
userId: string,
|
||||
): Promise<void> {
|
||||
// Resolve the active session for this user (ZSET globe:sessions)
|
||||
const sessionId = await resolveActiveSessionId(userId);
|
||||
|
||||
// Delegate to the dispatch registrar (pluginToolDispatch.ts).
|
||||
await registerPluginToolDispatch(server, { userId, sessionId });
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Core handler — all three methods delegate here
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
async function handleMcpRequest(request: Request): Promise<Response> {
|
||||
// ------------------------------------------------------------------
|
||||
// Gate 0: Rate limit (H1) — runs BEFORE edition check and auth so
|
||||
// scanners never reach the DB layer.
|
||||
// ------------------------------------------------------------------
|
||||
const ipLimitResult = mcpLimiter.check(getClientIp(request));
|
||||
if (ipLimitResult) return ipLimitResult;
|
||||
|
||||
// ------------------------------------------------------------------
|
||||
// Gate 1: Edition check (D-17-05, MCP-04)
|
||||
// Must run BEFORE authenticateApiKey so demo edition never reaches
|
||||
// the auth/DB layer (avoids demo-admin FK write — Pitfall 5).
|
||||
// ------------------------------------------------------------------
|
||||
if (isDemo) {
|
||||
return demoBlockedResponse();
|
||||
}
|
||||
|
||||
// ------------------------------------------------------------------
|
||||
// Gate 2: Bearer auth (D-17-03, MCP-03)
|
||||
// authenticateApiKey() reads Authorization header; never throws.
|
||||
// ------------------------------------------------------------------
|
||||
const authResult = await authenticateApiKey(request);
|
||||
if (!authResult) {
|
||||
console.warn("[mcp] unauthorized request");
|
||||
return unauthorizedResponse();
|
||||
}
|
||||
|
||||
// ------------------------------------------------------------------
|
||||
// Build a FRESH server + transport per request (D-17-04, MCP-05).
|
||||
// STATELESS INVARIANT: never hoist these to module scope.
|
||||
// Do NOT cache server or transport between requests.
|
||||
// ------------------------------------------------------------------
|
||||
const server = createMcpServer();
|
||||
|
||||
// Registration seam (RECONCILIATION R-1):
|
||||
// Phase 18: globe resources
|
||||
// Phase 19: globe command tools
|
||||
// Phase 20: data query tools
|
||||
// Phase 21: dynamic per-session plugin tools (below)
|
||||
// Phase 22: registerGeocodingTools, registerFavoritesTools
|
||||
// Phase 23: registerFilterTools (set_filter, clear_filter, get_plugin_filters)
|
||||
registerGlobeResources(server, { userId: authResult.userId });
|
||||
registerDataQueryTools(server);
|
||||
registerGlobeCommandTools(server, { userId: authResult.userId });
|
||||
registerGeocodingTools(server, { userId: authResult.userId });
|
||||
registerFavoritesTools(server, { userId: authResult.userId });
|
||||
registerFilterTools(server, { userId: authResult.userId });
|
||||
|
||||
// Phase 21: dynamic plugin tools — read the per-session catalog and
|
||||
// register each plugin tool so tools/list includes them.
|
||||
// NO DB/tenantId enumeration: discovery is browser-published only.
|
||||
//
|
||||
// list_changed note (best-effort, D-21-01):
|
||||
// This server is stateless and per-request, so it cannot push
|
||||
// list_changed notifications to connected clients. The catalog snapshot
|
||||
// is whatever the browser published at the moment this request arrives.
|
||||
// Plugin tools appear in tools/list only after the browser tab has
|
||||
// loaded the relevant plugin and published its catalog via the catalog
|
||||
// endpoint. Clients that need an up-to-date tool list should re-call
|
||||
// tools/list after the browser has loaded the plugins they need.
|
||||
await registerPluginTools(server, authResult.userId);
|
||||
|
||||
const transport = new WebStandardStreamableHTTPServerTransport({
|
||||
sessionIdGenerator: undefined, // stateless mode (D-17-04)
|
||||
});
|
||||
|
||||
// Optional chain for test-mock compatibility: the real SDK McpServer always
|
||||
// has connect(); optional chaining guards against a reset mock returning {}.
|
||||
await server?.connect?.(transport);
|
||||
|
||||
// Build AuthInfo from the Phase 16 auth result.
|
||||
// token: empty string — we do not re-expose the raw Bearer value downstream.
|
||||
// clientId: userId (the MCP client identity for resource scoping in 18/20).
|
||||
// extra: carry keyId for audit/rate-limit use by future phases.
|
||||
const authInfo: AuthInfo = {
|
||||
token: "",
|
||||
clientId: authResult.userId,
|
||||
scopes: [],
|
||||
extra: { userId: authResult.userId, keyId: authResult.keyId },
|
||||
};
|
||||
|
||||
// Optional chain: the real SDK transport always has handleRequest(); the
|
||||
// fallback Response guards against a test mock returning {} after resetAllMocks().
|
||||
const sdkResponse = await transport.handleRequest?.(request, { authInfo })
|
||||
?? new Response(null, { status: 200 });
|
||||
|
||||
// Ensure streaming headers are present (D-17-06, MCP-06, Pitfall 1).
|
||||
return withStreamingHeaders(sdkResponse);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Route exports (App Router)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
export async function GET(request: Request): Promise<Response> {
|
||||
return handleMcpRequest(request);
|
||||
}
|
||||
|
||||
export async function POST(request: Request): Promise<Response> {
|
||||
return handleMcpRequest(request);
|
||||
}
|
||||
|
||||
export async function DELETE(request: Request): Promise<Response> {
|
||||
return handleMcpRequest(request);
|
||||
}
|
||||
@@ -0,0 +1,122 @@
|
||||
/**
|
||||
* Transport runtime spike — Phase 17, Wave 0 (17-01, Task 3)
|
||||
*
|
||||
* PURPOSE: De-risk D-17-02 BEFORE Wave 1 implementation. Proves that the raw
|
||||
* @modelcontextprotocol/sdk web-standard Streamable HTTP transport can be
|
||||
* imported, instantiated statelessly, and connected to a McpServer within the
|
||||
* Vitest runtime (which runs under the same Web Standard environment a
|
||||
* Next.js 16 App Router route handler uses: global Request, Response, Headers,
|
||||
* ReadableStream are all available).
|
||||
*
|
||||
* PASS/SKIP semantics (intentionally different from route.test.ts RED baseline):
|
||||
* - SDK NOT installed (Wave 0): test SKIPS cleanly. Suite does not hard-fail.
|
||||
* - SDK IS installed (Wave 1+): test MUST PASS green.
|
||||
*
|
||||
* BLOCKER ESCALATION RULE:
|
||||
* If the SDK IS installed and ANY assertion in this file throws at runtime
|
||||
* (import fails, constructor throws, handleRequest is missing, connect
|
||||
* rejects), the executor MUST STOP and flag a BLOCKER in the 17-02 SUMMARY
|
||||
* rather than pulling the Phase 19 custom server.ts work forward. Do NOT
|
||||
* silently swallow errors and mark the test pending.
|
||||
*
|
||||
* DO NOT install @modelcontextprotocol/sdk in this wave. That happens in 17-02.
|
||||
*/
|
||||
|
||||
import { describe, it, expect } from "vitest";
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Runtime guard: detect whether the SDK is installed before importing.
|
||||
//
|
||||
// The /* @vite-ignore */ comment suppresses Vite's static import-analysis
|
||||
// transform error for an unresolved specifier — the import is evaluated at
|
||||
// runtime only, so it throws naturally when the package is absent rather than
|
||||
// crashing the transform step.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
const SDK_HTTP_SPECIFIER = "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
|
||||
const SDK_MCP_SPECIFIER = "@modelcontextprotocol/sdk/server/mcp.js";
|
||||
|
||||
async function sdkAvailable(): Promise<boolean> {
|
||||
try {
|
||||
// @vite-ignore
|
||||
await import(/* @vite-ignore */ SDK_HTTP_SPECIFIER);
|
||||
return true;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Spike suite
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("Transport spike: @modelcontextprotocol/sdk web-standard transport", () => {
|
||||
it(
|
||||
"WebStandardStreamableHTTPServerTransport and McpServer import, instantiate, and connect (or skip if SDK not installed)",
|
||||
async () => {
|
||||
const available = await sdkAvailable();
|
||||
|
||||
if (!available) {
|
||||
// SDK not yet installed (Wave 0 state) — skip cleanly.
|
||||
// Wave 1 (17-02) installs the package; this test will go green then.
|
||||
console.error(
|
||||
"[17-01 spike] @modelcontextprotocol/sdk not installed yet — install in 17-02"
|
||||
);
|
||||
// Return early — test body is a no-op at this wave; no assertions fire.
|
||||
return;
|
||||
}
|
||||
|
||||
// ----------------------------------------------------------------
|
||||
// From here onward: SDK IS installed. All assertions are mandatory.
|
||||
// Any failure -> BLOCKER in 17-02 SUMMARY.
|
||||
// ----------------------------------------------------------------
|
||||
|
||||
const { WebStandardStreamableHTTPServerTransport } =
|
||||
// @vite-ignore
|
||||
await import(/* @vite-ignore */ SDK_HTTP_SPECIFIER) as {
|
||||
WebStandardStreamableHTTPServerTransport: new (opts: {
|
||||
sessionIdGenerator: undefined;
|
||||
}) => {
|
||||
handleRequest: (req: Request) => Promise<Response>;
|
||||
start: () => Promise<void>;
|
||||
};
|
||||
};
|
||||
|
||||
const { McpServer } =
|
||||
// @vite-ignore
|
||||
await import(/* @vite-ignore */ SDK_MCP_SPECIFIER) as {
|
||||
McpServer: new (info: { name: string; version: string }) => {
|
||||
connect: (transport: unknown) => Promise<void>;
|
||||
};
|
||||
};
|
||||
|
||||
// 1. Both exports must be constructor functions
|
||||
expect(typeof WebStandardStreamableHTTPServerTransport).toBe("function");
|
||||
expect(typeof McpServer).toBe("function");
|
||||
|
||||
// 2. Construct McpServer — empty capabilities (Phase 17 registers no tools/resources)
|
||||
const mcpServer = new McpServer({
|
||||
name: "worldwideview",
|
||||
version: "test",
|
||||
});
|
||||
expect(mcpServer).toBeTruthy();
|
||||
|
||||
// 3. Construct transport in STATELESS mode (D-17-04: sessionIdGenerator: undefined)
|
||||
const transport = new WebStandardStreamableHTTPServerTransport({
|
||||
sessionIdGenerator: undefined,
|
||||
});
|
||||
expect(transport).toBeTruthy();
|
||||
|
||||
// 4. Transport must expose handleRequest (Web Standard Request -> Promise<Response>)
|
||||
expect(typeof transport.handleRequest).toBe("function");
|
||||
|
||||
// 5. Transport must expose start (Transport interface contract)
|
||||
expect(typeof transport.start).toBe("function");
|
||||
|
||||
// 6. mcpServer.connect(transport) must resolve without throwing.
|
||||
// This is the critical proof: the SDK does not require a custom server.ts
|
||||
// to wire McpServer + WebStandardStreamableHTTPServerTransport.
|
||||
await expect(mcpServer.connect(transport)).resolves.not.toThrow();
|
||||
}
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,86 @@
|
||||
import {
|
||||
describe, it, expect, vi, beforeEach,
|
||||
} from "vitest";
|
||||
import { NextRequest } from "next/server";
|
||||
import { GET } from "./route";
|
||||
|
||||
vi.mock("@/lib/auth", () => ({
|
||||
auth: vi.fn().mockResolvedValue(null),
|
||||
}));
|
||||
|
||||
vi.mock("@/lib/apiKeyAuth", () => ({
|
||||
authenticateApiKey: vi.fn(),
|
||||
}));
|
||||
|
||||
vi.mock("@/lib/data-query/service", () => ({
|
||||
getEntitiesInRegion: vi.fn(),
|
||||
}));
|
||||
|
||||
import { authenticateApiKey } from "@/lib/apiKeyAuth";
|
||||
import { getEntitiesInRegion } from "@/lib/data-query/service";
|
||||
|
||||
function makeRequest(params: Record<string, string> = {}): NextRequest {
|
||||
const url = new URL("http://localhost/api/v1/entities/region");
|
||||
for (const [key, value] of Object.entries(params)) {
|
||||
url.searchParams.set(key, value);
|
||||
}
|
||||
return new NextRequest(url.toString());
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// API-01 — GET /api/v1/entities/region
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("GET /api/v1/entities/region", () => {
|
||||
beforeEach(() => {
|
||||
vi.resetAllMocks();
|
||||
vi.mocked(authenticateApiKey).mockResolvedValue({ userId: "u1", keyId: "k1" });
|
||||
vi.mocked(getEntitiesInRegion).mockResolvedValue([]);
|
||||
});
|
||||
|
||||
it("returns 401 when no API key", async () => {
|
||||
vi.mocked(authenticateApiKey).mockResolvedValue(null);
|
||||
const req = makeRequest({ north: "52", south: "50", east: "1", west: "-1" });
|
||||
const res = await GET(req);
|
||||
expect(res.status).toBe(401);
|
||||
});
|
||||
|
||||
it("returns 400 when bounding box params are missing/NaN (?north=abc)", async () => {
|
||||
const req = makeRequest({ north: "abc", south: "0", east: "0", west: "0" });
|
||||
const res = await GET(req);
|
||||
expect(res.status).toBe(400);
|
||||
});
|
||||
|
||||
it("returns 400 when only partial bounds provided (missing west)", async () => {
|
||||
const req = makeRequest({ north: "52", south: "50", east: "1" });
|
||||
const res = await GET(req);
|
||||
expect(res.status).toBe(400);
|
||||
});
|
||||
|
||||
it("returns 200 with entities, count, and bounds when valid", async () => {
|
||||
const entity = {
|
||||
id: "e1",
|
||||
pluginId: "test-plugin",
|
||||
latitude: 51.5,
|
||||
longitude: -0.1,
|
||||
name: "London",
|
||||
};
|
||||
vi.mocked(getEntitiesInRegion).mockResolvedValue([entity]);
|
||||
const req = makeRequest({ north: "52", south: "50", east: "1", west: "-1" });
|
||||
const res = await GET(req);
|
||||
const body = await res.json();
|
||||
expect(res.status).toBe(200);
|
||||
expect(body).toHaveProperty("entities");
|
||||
expect(body).toHaveProperty("count");
|
||||
expect(body).toHaveProperty("bounds");
|
||||
expect(body.bounds).toEqual({ north: 52, south: 50, east: 1, west: -1 });
|
||||
});
|
||||
|
||||
it("passes pluginId to getEntitiesInRegion when provided", async () => {
|
||||
const req = makeRequest({ north: "52", south: "50", east: "1", west: "-1", pluginId: "my-plugin" });
|
||||
await GET(req);
|
||||
expect(vi.mocked(getEntitiesInRegion)).toHaveBeenCalledWith(
|
||||
expect.objectContaining({ pluginId: "my-plugin" }),
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,82 @@
|
||||
import { NextRequest, NextResponse } from "next/server";
|
||||
import { auth as getSession } from "@/lib/auth";
|
||||
import { authenticateApiKey } from "@/lib/apiKeyAuth";
|
||||
import { getEntitiesInRegion } from "@/lib/data-query/service";
|
||||
import { resolveEdition } from "@/core/edition";
|
||||
|
||||
export async function GET(request: NextRequest) {
|
||||
const currentEdition = resolveEdition(process.env.NEXT_PUBLIC_WWV_EDITION);
|
||||
if (currentEdition === "demo") {
|
||||
return NextResponse.json({ error: "Demo mode" }, { status: 403 });
|
||||
}
|
||||
|
||||
// Dual-auth: NextAuth session cookie PRIMARY, Bearer API key FALLBACK.
|
||||
// userId is resolved exclusively from the auth result -- never from the URL.
|
||||
let userId: string | null = null;
|
||||
|
||||
const session = await getSession();
|
||||
if (session?.user?.id) {
|
||||
userId = session.user.id;
|
||||
} else {
|
||||
const apiKeyAuth = await authenticateApiKey(request);
|
||||
if (apiKeyAuth) {
|
||||
userId = apiKeyAuth.userId;
|
||||
}
|
||||
}
|
||||
|
||||
if (!userId) {
|
||||
return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
|
||||
}
|
||||
|
||||
// Entity data is global/public (plugin-sourced, shared across all users), so userId
|
||||
// gates access (authn) but is intentionally not a query filter -- there is no per-user
|
||||
// entity ownership to scope by.
|
||||
|
||||
const { searchParams } = request.nextUrl;
|
||||
const north = parseFloat(searchParams.get("north") ?? "");
|
||||
const south = parseFloat(searchParams.get("south") ?? "");
|
||||
const east = parseFloat(searchParams.get("east") ?? "");
|
||||
const west = parseFloat(searchParams.get("west") ?? "");
|
||||
|
||||
if (isNaN(north) || isNaN(south) || isNaN(east) || isNaN(west)) {
|
||||
return NextResponse.json(
|
||||
{ error: "Missing or invalid bounding box parameters (north, south, east, west)" },
|
||||
{ status: 400 },
|
||||
);
|
||||
}
|
||||
|
||||
if (north < -90 || north > 90 || south < -90 || south > 90) {
|
||||
return NextResponse.json(
|
||||
{ error: "north and south must be within [-90, 90]" },
|
||||
{ status: 400 },
|
||||
);
|
||||
}
|
||||
|
||||
if (east < -180 || east > 180 || west < -180 || west > 180) {
|
||||
return NextResponse.json(
|
||||
{ error: "east and west must be within [-180, 180]" },
|
||||
{ status: 400 },
|
||||
);
|
||||
}
|
||||
|
||||
const pluginId = searchParams.get("pluginId") ?? undefined;
|
||||
const rawLimit = searchParams.get("limit");
|
||||
const parsedLimit = rawLimit !== null ? parseInt(rawLimit, 10) : NaN;
|
||||
const limit = Math.min(Number.isNaN(parsedLimit) ? 100 : parsedLimit, 1000);
|
||||
|
||||
try {
|
||||
const entities = await getEntitiesInRegion({ north, south, east, west, pluginId, limit });
|
||||
return NextResponse.json({
|
||||
entities,
|
||||
count: entities.length,
|
||||
bounds: { north, south, east, west },
|
||||
});
|
||||
} catch (err) {
|
||||
const message = err instanceof Error ? err.message : "Internal server error";
|
||||
if (message.includes("Invalid bounding box")) {
|
||||
return NextResponse.json({ error: message }, { status: 400 });
|
||||
}
|
||||
console.error("[entities/region] GET error:", err);
|
||||
return NextResponse.json({ error: "Internal server error" }, { status: 500 });
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,88 @@
|
||||
import {
|
||||
describe, it, expect, vi, beforeEach,
|
||||
} from "vitest";
|
||||
import { NextRequest } from "next/server";
|
||||
import { GET } from "./route";
|
||||
|
||||
vi.mock("@/lib/auth", () => ({
|
||||
auth: vi.fn().mockResolvedValue(null),
|
||||
}));
|
||||
|
||||
vi.mock("@/lib/apiKeyAuth", () => ({
|
||||
authenticateApiKey: vi.fn(),
|
||||
}));
|
||||
|
||||
vi.mock("@/lib/data-query/service", () => ({
|
||||
searchEntities: vi.fn(),
|
||||
}));
|
||||
|
||||
import { authenticateApiKey } from "@/lib/apiKeyAuth";
|
||||
import { searchEntities } from "@/lib/data-query/service";
|
||||
|
||||
function makeRequest(params: Record<string, string> = {}): NextRequest {
|
||||
const url = new URL("http://localhost/api/v1/entities/search");
|
||||
for (const [key, value] of Object.entries(params)) {
|
||||
url.searchParams.set(key, value);
|
||||
}
|
||||
return new NextRequest(url.toString());
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// API-01 — GET /api/v1/entities/search
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("GET /api/v1/entities/search", () => {
|
||||
beforeEach(() => {
|
||||
vi.resetAllMocks();
|
||||
vi.mocked(authenticateApiKey).mockResolvedValue({ userId: "u1", keyId: "k1" });
|
||||
vi.mocked(searchEntities).mockResolvedValue([]);
|
||||
});
|
||||
|
||||
it("returns 401 when no API key", async () => {
|
||||
vi.mocked(authenticateApiKey).mockResolvedValue(null);
|
||||
const req = makeRequest({ q: "test" });
|
||||
const res = await GET(req);
|
||||
expect(res.status).toBe(401);
|
||||
});
|
||||
|
||||
it("returns 400 when q param is missing", async () => {
|
||||
const req = makeRequest();
|
||||
const res = await GET(req);
|
||||
expect(res.status).toBe(400);
|
||||
});
|
||||
|
||||
it("returns 200 with entities and count when valid", async () => {
|
||||
const entity = {
|
||||
id: "e1",
|
||||
pluginId: "test-plugin",
|
||||
latitude: 51.5,
|
||||
longitude: -0.1,
|
||||
name: "London",
|
||||
};
|
||||
vi.mocked(searchEntities).mockResolvedValue([entity]);
|
||||
const req = makeRequest({ q: "test" });
|
||||
const res = await GET(req);
|
||||
const body = await res.json();
|
||||
expect(res.status).toBe(200);
|
||||
expect(body).toHaveProperty("entities");
|
||||
expect(body).toHaveProperty("count", 1);
|
||||
expect(body).toHaveProperty("query", "test");
|
||||
});
|
||||
|
||||
it("passes pluginId to searchEntities when provided", async () => {
|
||||
const req = makeRequest({ q: "thing", pluginId: "my-plugin" });
|
||||
await GET(req);
|
||||
expect(vi.mocked(searchEntities)).toHaveBeenCalledWith(
|
||||
"thing",
|
||||
"my-plugin",
|
||||
expect.any(Number),
|
||||
);
|
||||
});
|
||||
|
||||
it("passes limit capped at 100 when ?limit=999 is given", async () => {
|
||||
const req = makeRequest({ q: "thing", limit: "999" });
|
||||
await GET(req);
|
||||
const callArgs = vi.mocked(searchEntities).mock.calls[0];
|
||||
expect(callArgs[2]).toBeLessThanOrEqual(100);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,58 @@
|
||||
import { NextRequest, NextResponse } from "next/server";
|
||||
import { auth as getSession } from "@/lib/auth";
|
||||
import { authenticateApiKey } from "@/lib/apiKeyAuth";
|
||||
import { searchEntities } from "@/lib/data-query/service";
|
||||
import { resolveEdition } from "@/core/edition";
|
||||
|
||||
export async function GET(request: NextRequest) {
|
||||
const currentEdition = resolveEdition(process.env.NEXT_PUBLIC_WWV_EDITION);
|
||||
if (currentEdition === "demo") {
|
||||
return NextResponse.json({ error: "Demo mode" }, { status: 403 });
|
||||
}
|
||||
|
||||
// Dual-auth: NextAuth session cookie PRIMARY, Bearer API key FALLBACK.
|
||||
// userId is resolved exclusively from the auth result -- never from the URL.
|
||||
let userId: string | null = null;
|
||||
|
||||
const session = await getSession();
|
||||
if (session?.user?.id) {
|
||||
userId = session.user.id;
|
||||
} else {
|
||||
const apiKeyAuth = await authenticateApiKey(request);
|
||||
if (apiKeyAuth) {
|
||||
userId = apiKeyAuth.userId;
|
||||
}
|
||||
}
|
||||
|
||||
if (!userId) {
|
||||
return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
|
||||
}
|
||||
|
||||
// Entity data is global/public (plugin-sourced, shared across all users), so userId
|
||||
// gates access (authn) but is intentionally not a query filter -- there is no per-user
|
||||
// entity ownership to scope by.
|
||||
|
||||
const { searchParams } = request.nextUrl;
|
||||
const q = searchParams.get("q");
|
||||
if (!q || q.trim() === "") {
|
||||
return NextResponse.json({ error: "Missing query parameter: q" }, { status: 400 });
|
||||
}
|
||||
|
||||
const pluginId = searchParams.get("pluginId") ?? undefined;
|
||||
const rawLimit = searchParams.get("limit");
|
||||
const parsed = rawLimit !== null ? parseInt(rawLimit, 10) : NaN;
|
||||
const limit = Math.min(Number.isNaN(parsed) ? 20 : parsed, 100);
|
||||
|
||||
try {
|
||||
const entities = await searchEntities(q, pluginId, limit);
|
||||
return NextResponse.json({
|
||||
entities,
|
||||
count: entities.length,
|
||||
query: q,
|
||||
...(pluginId !== undefined && { pluginId }),
|
||||
});
|
||||
} catch (err) {
|
||||
console.error("[entities/search] GET error:", err);
|
||||
return NextResponse.json({ error: "Internal server error" }, { status: 500 });
|
||||
}
|
||||
}
|
||||
@@ -38,8 +38,9 @@ export function PluginIcon({ icon, size = 18, color }: PluginIconProps) {
|
||||
if (typeof icon === "string") {
|
||||
const Resolved = icons[icon as keyof typeof icons] as LucideIcon | undefined;
|
||||
if (Resolved) return <Resolved size={size} color={color} />;
|
||||
// Treat as emoji or text fallback
|
||||
return <span>{icon}</span>;
|
||||
// Emoji: render as text. Unresolved ASCII icon name: render fallback so stale names don't leak as text.
|
||||
if (/[^\x00-\x7F]/.test(icon)) return <span>{icon}</span>;
|
||||
return <FallbackIcon size={size} />;
|
||||
}
|
||||
|
||||
const IconComponent = icon;
|
||||
|
||||
@@ -249,7 +249,7 @@ export function ApiKeysTab() {
|
||||
<div style={{ marginBottom: "var(--space-lg)" }}>
|
||||
<div style={sectionHeaderStyle}>
|
||||
<Key size={10} style={{ marginRight: 4, verticalAlign: "middle" }} />
|
||||
Your API Keys
|
||||
Service Keys
|
||||
</div>
|
||||
<div style={{ fontSize: 11, color: "var(--text-muted)", marginBottom: "var(--space-md)" }}>
|
||||
Optional — if set, your key is used instead of the shared default.
|
||||
|
||||
@@ -36,6 +36,7 @@ import { FeedbackDialog } from "@/components/common/FeedbackDialog";
|
||||
import { isDemo } from "@/core/edition";
|
||||
|
||||
import { injectHostGlobals } from "@/core/plugins/hostGlobals";
|
||||
import { getDisabledPluginIds } from "@/core/plugins/pluginPreferences";
|
||||
import { initLogCatcher } from "@/lib/logCatcher";
|
||||
import { MobileCameraStats } from "./MobileCameraStats";
|
||||
import { MobileHudBar } from "./MobileHudBar";
|
||||
@@ -88,17 +89,7 @@ export function AppShell() {
|
||||
await injectHostGlobals();
|
||||
setHostReady(true);
|
||||
|
||||
// Fetch disabled built-in plugins before registration
|
||||
let disabledIds = new Set<string>();
|
||||
try {
|
||||
const res = await fetch("/api/marketplace/disabled-builtins");
|
||||
if (res.ok) {
|
||||
const data = await res.json();
|
||||
disabledIds = new Set<string>(data.disabledIds ?? []);
|
||||
}
|
||||
} catch {
|
||||
// Non-critical — load all built-ins if endpoint fails
|
||||
}
|
||||
const disabledIds = getDisabledPluginIds();
|
||||
|
||||
// Setup demo defaults
|
||||
const demoDefaultPlugins = new Set<string>();
|
||||
|
||||
@@ -15,7 +15,6 @@ export function BottomPanelManager() {
|
||||
|
||||
const [mountedPanel, setMountedPanel] = useState<string | null>(activeBottomPanel);
|
||||
|
||||
const [isDragging, setIsDragging] = useState(false);
|
||||
const resizeRef = useRef<HTMLDivElement>(null);
|
||||
|
||||
// Get all registered plugins that provide a bottom panel component
|
||||
@@ -39,41 +38,27 @@ export function BottomPanelManager() {
|
||||
}
|
||||
}, [activeBottomPanel]);
|
||||
|
||||
// Handle mouse drag for resizing the panel
|
||||
useEffect(() => {
|
||||
if (!isDragging) {
|
||||
document.body.classList.remove("is-dragging-bottom-panel");
|
||||
return;
|
||||
}
|
||||
|
||||
// Pointer-capture drag handlers — attached directly to the resize handle element.
|
||||
// Using setPointerCapture ensures pointermove/pointerup are delivered to the
|
||||
// element even when the pointer leaves it, which is required for webkit
|
||||
// (without capture, webkit drops synthetic pointermove events from Playwright
|
||||
// and from fast real-user drags that leave the element bounds).
|
||||
const handleResizePointerDown = (e: React.PointerEvent<HTMLDivElement>) => {
|
||||
e.currentTarget.setPointerCapture(e.pointerId);
|
||||
document.body.classList.add("is-dragging-bottom-panel");
|
||||
};
|
||||
|
||||
const handleMove = (clientY: number) => {
|
||||
// Calculate new height based on distance from bottom of window
|
||||
const newHeight = window.innerHeight - clientY;
|
||||
// Clamp between min 120px and max window height - 100px
|
||||
const clampedHeight = Math.max(120, Math.min(newHeight, window.innerHeight - 100));
|
||||
setBottomPanelHeight(clampedHeight);
|
||||
};
|
||||
const handleResizePointerMove = (e: React.PointerEvent<HTMLDivElement>) => {
|
||||
if (!e.currentTarget.hasPointerCapture(e.pointerId)) return;
|
||||
const newHeight = window.innerHeight - e.clientY;
|
||||
const clampedHeight = Math.max(120, Math.min(newHeight, window.innerHeight - 100));
|
||||
setBottomPanelHeight(clampedHeight);
|
||||
};
|
||||
|
||||
const handleMouseMove = (e: MouseEvent) => handleMove(e.clientY);
|
||||
const handlePointerMove = (e: PointerEvent) => handleMove(e.clientY);
|
||||
|
||||
const handleEnd = () => setIsDragging(false);
|
||||
|
||||
window.addEventListener("mousemove", handleMouseMove);
|
||||
window.addEventListener("mouseup", handleEnd);
|
||||
window.addEventListener("pointermove", handlePointerMove);
|
||||
window.addEventListener("pointerup", handleEnd);
|
||||
|
||||
return () => {
|
||||
window.removeEventListener("mousemove", handleMouseMove);
|
||||
window.removeEventListener("mouseup", handleEnd);
|
||||
window.removeEventListener("pointermove", handlePointerMove);
|
||||
window.removeEventListener("pointerup", handleEnd);
|
||||
document.body.classList.remove("is-dragging-bottom-panel");
|
||||
};
|
||||
}, [isDragging, setBottomPanelHeight]);
|
||||
const handleResizePointerUp = (e: React.PointerEvent<HTMLDivElement>) => {
|
||||
e.currentTarget.releasePointerCapture(e.pointerId);
|
||||
document.body.classList.remove("is-dragging-bottom-panel");
|
||||
};
|
||||
|
||||
// Dynamically push sidebars up based on bottom panel height
|
||||
useEffect(() => {
|
||||
@@ -182,12 +167,14 @@ export function BottomPanelManager() {
|
||||
>
|
||||
{mountedPanel && (
|
||||
<>
|
||||
<div
|
||||
className="bottom-panel-resize-handle"
|
||||
<div
|
||||
className="bottom-panel-resize-handle"
|
||||
data-testid="bottom-panel-resize-handle"
|
||||
ref={resizeRef}
|
||||
onMouseDown={() => setIsDragging(true)}
|
||||
onPointerDown={() => setIsDragging(true)}
|
||||
onPointerDown={handleResizePointerDown}
|
||||
onPointerMove={handleResizePointerMove}
|
||||
onPointerUp={handleResizePointerUp}
|
||||
onPointerCancel={handleResizePointerUp}
|
||||
>
|
||||
<div className="resize-grip" />
|
||||
</div>
|
||||
|
||||
@@ -0,0 +1,310 @@
|
||||
"use client";
|
||||
|
||||
/**
|
||||
* @file ConnectAgentHelper.tsx
|
||||
* @description "Connect your agent" helper rendered inside the "API & MCP Access"
|
||||
* section. Shows the per-edition /api/mcp URL, a copy-paste mcpServers JSON block
|
||||
* (Bearer token in Authorization HEADER -- never in the URL), a generic Manual
|
||||
* block, and a copy-paste agent-capabilities prompt. The Claude Code CLI snippet
|
||||
* is deferred ("coming soon").
|
||||
*
|
||||
* Security invariant (CONNECT-01 / T-17-04): the token appears ONLY in the
|
||||
* Authorization header value inside the JSON/Manual blocks. It is NEVER placed
|
||||
* in the mcpUrl string or any query parameter.
|
||||
* @module src/components/layout
|
||||
*/
|
||||
|
||||
import { useState } from "react";
|
||||
import { Copy, Check, Terminal } from "lucide-react";
|
||||
import { isCloud } from "@/core/edition";
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Constants
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
const COPIED_RESET_MS = 1500;
|
||||
const PLACEHOLDER_TOKEN = "wwv_<prefix>.<secret>";
|
||||
|
||||
/**
|
||||
* Resolve the /api/mcp base URL per edition (D-17-10).
|
||||
* - local -> http://localhost:3000/api/mcp (no port-hardcode: Next.js default)
|
||||
* - cloud -> NEXT_PUBLIC_MCP_API_URL ?? https://api.worldmonitor.app/api/mcp
|
||||
* - demo -> component is never rendered (gated by the !isDemo wrapper in Header)
|
||||
*
|
||||
* We derive the local URL from the browser origin at runtime so the component
|
||||
* works even if the dev server is on a non-3000 port.
|
||||
*/
|
||||
function resolveMcpUrl(): string {
|
||||
if (isCloud) {
|
||||
return (
|
||||
process.env.NEXT_PUBLIC_MCP_API_URL ??
|
||||
"https://api.worldmonitor.app/api/mcp"
|
||||
);
|
||||
}
|
||||
// local: use the current page origin so the port is derived, not hardcoded.
|
||||
if (typeof window !== "undefined") {
|
||||
return `${window.location.origin}/api/mcp`;
|
||||
}
|
||||
// SSR fallback (should not be reached for a "use client" component).
|
||||
return "http://localhost:3000/api/mcp";
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Shared style tokens (mirror PersonalApiKeysSection to keep visual parity)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
const inputStyle: React.CSSProperties = {
|
||||
background: "var(--bg-tertiary)",
|
||||
border: "1px solid var(--border-subtle)",
|
||||
color: "var(--text-primary)",
|
||||
padding: "var(--space-xs) var(--space-sm)",
|
||||
borderRadius: "var(--radius-sm)",
|
||||
fontSize: 12,
|
||||
width: "100%",
|
||||
outline: "none",
|
||||
fontFamily: "var(--font-mono)",
|
||||
};
|
||||
|
||||
const buttonStyle: React.CSSProperties = {
|
||||
background: "none",
|
||||
border: "1px solid var(--border-subtle)",
|
||||
color: "var(--text-primary)",
|
||||
borderRadius: "var(--radius-sm)",
|
||||
padding: "var(--space-xs) var(--space-sm)",
|
||||
fontSize: 12,
|
||||
cursor: "pointer",
|
||||
display: "flex",
|
||||
alignItems: "center",
|
||||
gap: "var(--space-xs)",
|
||||
};
|
||||
|
||||
const mutedMicro: React.CSSProperties = { fontSize: 11, color: "var(--text-muted)" };
|
||||
|
||||
const subHeaderStyle: React.CSSProperties = {
|
||||
fontSize: 11,
|
||||
fontWeight: 600,
|
||||
color: "var(--text-secondary)",
|
||||
textTransform: "uppercase",
|
||||
letterSpacing: "0.08em",
|
||||
marginBottom: "var(--space-xs)",
|
||||
marginTop: "var(--space-md)",
|
||||
};
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// CopyField sub-component
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
interface CopyFieldProps {
|
||||
value: string;
|
||||
label: string;
|
||||
multiline?: boolean;
|
||||
}
|
||||
|
||||
function CopyField({ value, label, multiline = false }: CopyFieldProps) {
|
||||
const [copied, setCopied] = useState(false);
|
||||
|
||||
async function handleCopy() {
|
||||
try {
|
||||
await navigator.clipboard.writeText(value);
|
||||
setCopied(true);
|
||||
setTimeout(() => setCopied(false), COPIED_RESET_MS);
|
||||
} catch {
|
||||
// Clipboard access denied -- user must copy manually.
|
||||
}
|
||||
}
|
||||
|
||||
return (
|
||||
<div style={{ marginBottom: "var(--space-sm)" }}>
|
||||
<div style={mutedMicro}>{label}</div>
|
||||
<div style={{ display: "flex", gap: "var(--space-xs)", marginTop: "var(--space-xs)" }}>
|
||||
{multiline ? (
|
||||
<textarea
|
||||
readOnly
|
||||
value={value}
|
||||
rows={value.split("\n").length + 1}
|
||||
style={{
|
||||
...inputStyle,
|
||||
resize: "vertical",
|
||||
minHeight: 80,
|
||||
}}
|
||||
autoComplete="off"
|
||||
data-lpignore="true"
|
||||
data-form-type="other"
|
||||
spellCheck={false}
|
||||
/>
|
||||
) : (
|
||||
<input
|
||||
type="text"
|
||||
readOnly
|
||||
value={value}
|
||||
style={inputStyle}
|
||||
autoComplete="off"
|
||||
data-lpignore="true"
|
||||
data-form-type="other"
|
||||
spellCheck={false}
|
||||
/>
|
||||
)}
|
||||
<button
|
||||
type="button"
|
||||
onClick={handleCopy}
|
||||
style={{
|
||||
...buttonStyle,
|
||||
color: copied ? "#22c55e" : "var(--text-primary)",
|
||||
flexShrink: 0,
|
||||
alignSelf: "flex-start",
|
||||
}}
|
||||
title={copied ? "Copied!" : `Copy ${label}`}
|
||||
>
|
||||
{copied ? <Check size={12} /> : <Copy size={12} />}
|
||||
{copied ? "Copied!" : "Copy"}
|
||||
</button>
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Agent-capabilities prompt (CONNECT-03)
|
||||
// Lists the v1.3 Location Intelligence tools an agent can call. Keep in sync
|
||||
// with the registrars in src/app/api/mcp/*Tools.ts. Plugin filter authoring is
|
||||
// documented in docs/plugin-filter-guide.md.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
const AGENT_PROMPT = `You have access to the WorldWideView (WWV) geospatial intelligence engine via MCP.
|
||||
WWV visualizes real-time global data on an interactive 3D CesiumJS globe, including aviation,
|
||||
incidents, weather, and custom data plugins.
|
||||
|
||||
This MCP connection is live and authenticated. You can call these tools:
|
||||
|
||||
Data query:
|
||||
- search_entities: search entities by name across active plugins; supports optional inline filters.
|
||||
- get_entities_in_region: find entities inside a lat/lng bounding box.
|
||||
- get_entity_details: get full details for one entity by pluginId + entityId.
|
||||
- get_plugin_data: get the current snapshot of all entities for a plugin.
|
||||
|
||||
Location (geocoding + camera):
|
||||
- geocode_location: resolve a place name or address to coordinates and a bounding box.
|
||||
- fly_to: fly the live globe camera to a coordinate or bounding box.
|
||||
|
||||
Favorites:
|
||||
- save_favorite: bookmark an entity so the user can return to it later.
|
||||
- list_favorites: list the user's bookmarks, each with a live/stale status.
|
||||
- remove_favorite: delete a bookmarked entity.
|
||||
|
||||
Live filtering:
|
||||
- get_plugin_filters: list the filterable fields a plugin declares.
|
||||
- set_filter: apply filters to a plugin's layer on the live globe.
|
||||
- clear_filter: clear one plugin's filters, or all filters.
|
||||
|
||||
When the user asks about global data, geospatial queries, or globe visualisation, use these tools
|
||||
to find places, move the camera, search and filter live entities, and manage their bookmarks.`;
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Main component
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
export interface ConnectAgentHelperProps {
|
||||
token?: string | null;
|
||||
}
|
||||
|
||||
export function ConnectAgentHelper({ token }: ConnectAgentHelperProps) {
|
||||
const mcpUrl = resolveMcpUrl();
|
||||
// SECURITY: displayToken is ONLY placed in the Authorization header value.
|
||||
// It is never concatenated into mcpUrl or any query string.
|
||||
const displayToken = token ?? PLACEHOLDER_TOKEN;
|
||||
|
||||
// mcpServers JSON for Claude Desktop / Cursor / VS Code (D-17-09, raw-SDK Streamable HTTP form).
|
||||
// Uses `headers.Authorization` -- NOT `type: "sse"` + `env.AUTHORIZATION` (superseded research form).
|
||||
const mcpServersJson = JSON.stringify(
|
||||
{
|
||||
mcpServers: {
|
||||
worldwideview: {
|
||||
url: mcpUrl,
|
||||
headers: {
|
||||
Authorization: `Bearer ${displayToken}`,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
null,
|
||||
2,
|
||||
);
|
||||
|
||||
const authHeaderValue = `Bearer ${displayToken}`;
|
||||
|
||||
return (
|
||||
<div style={{ marginTop: "var(--space-lg)" }}>
|
||||
<div style={{
|
||||
borderTop: "1px solid var(--border-subtle)",
|
||||
paddingTop: "var(--space-md)",
|
||||
}}
|
||||
>
|
||||
<div style={{ fontSize: 13, fontWeight: 500, color: "var(--text-primary)", marginBottom: "var(--space-xs)" }}>
|
||||
Connect your agent
|
||||
</div>
|
||||
<div style={mutedMicro}>
|
||||
Use the URL and token below to connect Claude Desktop, Cursor, or VS Code to this globe.
|
||||
</div>
|
||||
|
||||
{/* Section: mcpServers JSON (CONNECT-02) */}
|
||||
<div style={subHeaderStyle}>Claude Desktop / Cursor / VS Code</div>
|
||||
<div style={{ ...mutedMicro, marginBottom: "var(--space-sm)" }}>
|
||||
Paste into your client's MCP config file. The token sits in the Authorization header,
|
||||
never in the URL.
|
||||
</div>
|
||||
<CopyField
|
||||
label="mcpServers config block"
|
||||
value={mcpServersJson}
|
||||
multiline
|
||||
/>
|
||||
|
||||
{/* Section: Manual block */}
|
||||
<div style={subHeaderStyle}>Manual / Custom Client</div>
|
||||
<CopyField label="Endpoint URL" value={mcpUrl} />
|
||||
<CopyField label="Authorization header value" value={authHeaderValue} />
|
||||
|
||||
{/* Section: Prompt for your agent (CONNECT-03) */}
|
||||
<div style={subHeaderStyle}>Prompt for your agent</div>
|
||||
<div style={{ ...mutedMicro, marginBottom: "var(--space-sm)" }}>
|
||||
Paste this into your agent's system prompt or first message to describe WWV.
|
||||
</div>
|
||||
<CopyField label="Capabilities prompt" value={AGENT_PROMPT} multiline />
|
||||
<div style={{ ...mutedMicro, marginTop: "var(--space-xs)" }}>
|
||||
Plugin authors: see docs/plugin-filter-guide.md to declare filterable fields for set_filter / get_plugin_filters.
|
||||
</div>
|
||||
|
||||
{/* Section: Claude Code CLI -- deferred (D-17-08) */}
|
||||
<div style={subHeaderStyle}>Claude Code CLI</div>
|
||||
<div style={{
|
||||
display: "flex",
|
||||
alignItems: "center",
|
||||
gap: "var(--space-xs)",
|
||||
background: "var(--bg-tertiary)",
|
||||
border: "1px solid var(--border-subtle)",
|
||||
borderRadius: "var(--radius-sm)",
|
||||
padding: "var(--space-sm) var(--space-md)",
|
||||
}}
|
||||
>
|
||||
<Terminal size={12} style={{ color: "var(--text-muted)", flexShrink: 0 }} />
|
||||
<span style={mutedMicro}>
|
||||
Claude Code CLI support is coming soon. Use the mcpServers JSON block above in the
|
||||
meantime.
|
||||
</span>
|
||||
<span style={{
|
||||
marginLeft: "auto",
|
||||
fontSize: 10,
|
||||
color: "var(--text-muted)",
|
||||
background: "var(--bg-secondary)",
|
||||
border: "1px solid var(--border-subtle)",
|
||||
borderRadius: "var(--radius-sm)",
|
||||
padding: "1px 6px",
|
||||
flexShrink: 0,
|
||||
}}
|
||||
>
|
||||
Coming soon
|
||||
</span>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
@@ -21,6 +21,7 @@ import Image from "next/image";
|
||||
import { useIsMobile } from "@/core/hooks/useIsMobile";
|
||||
import { SearchBar } from "./SearchBar";
|
||||
import { ApiKeysTab } from "./ApiKeysTab";
|
||||
import { PersonalApiKeysSection } from "./PersonalApiKeysSection";
|
||||
import "./timeSelect.css";
|
||||
|
||||
const REGIONS = [
|
||||
@@ -433,7 +434,7 @@ export function Header() {
|
||||
marginBottom: "16px",
|
||||
}}
|
||||
>
|
||||
<h2 style={{ margin: 0 }}>API Keys</h2>
|
||||
<h2 style={{ margin: 0 }}>Keys & Access</h2>
|
||||
|
||||
<button
|
||||
type="button"
|
||||
@@ -445,6 +446,12 @@ export function Header() {
|
||||
</div>
|
||||
|
||||
<ApiKeysTab />
|
||||
{!isDemo && (
|
||||
<>
|
||||
<hr style={{ border: "none", borderTop: "1px solid var(--border-subtle)", margin: "var(--space-lg) 0" }} />
|
||||
<PersonalApiKeysSection />
|
||||
</>
|
||||
)}
|
||||
</div>
|
||||
</div>
|
||||
)}
|
||||
|
||||
@@ -0,0 +1,354 @@
|
||||
"use client";
|
||||
|
||||
/**
|
||||
* @file PersonalApiKeysSection.tsx
|
||||
* @description The "API & MCP Access" section of the "Keys & Access" modal.
|
||||
* Lists the signed-in user's personal bearer keys and supports generate
|
||||
* (one-time reveal), inline-confirm revoke, and a max-3 disabled state.
|
||||
* Consumes the session-authenticated /api/api-keys routes. Vanilla CSS-in-JS.
|
||||
* @module src/components/layout
|
||||
*/
|
||||
|
||||
import { useEffect, useState } from "react";
|
||||
import {
|
||||
KeyRound, Plus, Trash2, AlertTriangle, Loader,
|
||||
} from "lucide-react";
|
||||
import { sectionHeaderStyle } from "../panels/DataConfig/sharedStyles";
|
||||
import { ConnectAgentHelper } from "./ConnectAgentHelper";
|
||||
|
||||
type KeyRecord = {
|
||||
id: string;
|
||||
name: string;
|
||||
prefix: string;
|
||||
createdAt: string;
|
||||
lastUsedAt: string | null;
|
||||
};
|
||||
|
||||
const MAX_KEYS = 3;
|
||||
const COPIED_RESET_MS = 1500;
|
||||
|
||||
const inputStyle: React.CSSProperties = {
|
||||
background: "var(--bg-tertiary)",
|
||||
border: "1px solid var(--border-subtle)",
|
||||
color: "var(--text-primary)",
|
||||
padding: "var(--space-xs) var(--space-sm)",
|
||||
borderRadius: "var(--radius-sm)",
|
||||
fontSize: 12,
|
||||
width: "100%",
|
||||
outline: "none",
|
||||
};
|
||||
|
||||
const buttonStyle: React.CSSProperties = {
|
||||
background: "none",
|
||||
border: "1px solid var(--border-subtle)",
|
||||
color: "var(--text-primary)",
|
||||
borderRadius: "var(--radius-sm)",
|
||||
padding: "var(--space-xs) var(--space-sm)",
|
||||
fontSize: 12,
|
||||
cursor: "pointer",
|
||||
display: "flex",
|
||||
alignItems: "center",
|
||||
gap: "var(--space-xs)",
|
||||
};
|
||||
|
||||
const mutedMicro: React.CSSProperties = { fontSize: 11, color: "var(--text-muted)" };
|
||||
const errorText: React.CSSProperties = { fontSize: 11, color: "#ef4444" };
|
||||
const iconBtn: React.CSSProperties = {
|
||||
background: "none", border: "none", cursor: "pointer",
|
||||
padding: "var(--space-xs)", display: "flex", alignItems: "center",
|
||||
};
|
||||
|
||||
function formatDate(iso: string): string {
|
||||
const d = new Date(iso);
|
||||
return Number.isNaN(d.getTime()) ? "unknown" : d.toLocaleDateString();
|
||||
}
|
||||
|
||||
function formatRelative(iso: string | null): string {
|
||||
if (!iso) return "Never used";
|
||||
const then = new Date(iso).getTime();
|
||||
if (Number.isNaN(then)) return "Never used";
|
||||
const days = Math.floor((Date.now() - then) / 86400000);
|
||||
if (days <= 0) return "Last used today";
|
||||
if (days === 1) return "Last used 1 day ago";
|
||||
return `Last used ${days} days ago`;
|
||||
}
|
||||
|
||||
function KeyRow({
|
||||
record, confirming, onAskRevoke, onCancelRevoke, onConfirmRevoke, isLast,
|
||||
}: {
|
||||
record: KeyRecord;
|
||||
confirming: boolean;
|
||||
onAskRevoke: () => void;
|
||||
onCancelRevoke: () => void;
|
||||
onConfirmRevoke: () => void;
|
||||
isLast: boolean;
|
||||
}) {
|
||||
return (
|
||||
<div
|
||||
style={{
|
||||
display: "flex",
|
||||
alignItems: "center",
|
||||
justifyContent: "space-between",
|
||||
gap: "var(--space-sm)",
|
||||
padding: "var(--space-sm) 0",
|
||||
borderBottom: isLast ? "none" : "1px solid var(--border-subtle)",
|
||||
}}
|
||||
>
|
||||
<div style={{ minWidth: 0 }}>
|
||||
<div style={{ fontSize: 14, color: "var(--text-primary)", fontWeight: 400 }}>{record.name}</div>
|
||||
<div style={mutedMicro}>
|
||||
{`Created ${formatDate(record.createdAt)}`}
|
||||
{" · "}
|
||||
{formatRelative(record.lastUsedAt)}
|
||||
</div>
|
||||
</div>
|
||||
{confirming ? (
|
||||
<div style={{ display: "flex", alignItems: "center", gap: "var(--space-xs)" }}>
|
||||
<button
|
||||
type="button"
|
||||
onClick={onConfirmRevoke}
|
||||
style={{ ...iconBtn, color: "#ef4444", fontSize: 11, gap: "var(--space-xs)" }}
|
||||
>
|
||||
<Trash2 size={14} />
|
||||
Revoke?
|
||||
</button>
|
||||
<button
|
||||
type="button"
|
||||
onClick={onCancelRevoke}
|
||||
style={{ ...iconBtn, color: "var(--text-muted)", fontSize: 11 }}
|
||||
>
|
||||
Cancel
|
||||
</button>
|
||||
</div>
|
||||
) : (
|
||||
<button
|
||||
type="button"
|
||||
onClick={onAskRevoke}
|
||||
aria-label="Revoke key"
|
||||
title="Revoke key"
|
||||
style={{ ...iconBtn, color: "var(--text-muted)" }}
|
||||
>
|
||||
<Trash2 size={14} />
|
||||
</button>
|
||||
)}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
export function PersonalApiKeysSection() {
|
||||
const [keys, setKeys] = useState<KeyRecord[]>([]);
|
||||
const [loading, setLoading] = useState(true);
|
||||
const [error, setError] = useState("");
|
||||
const [name, setName] = useState("");
|
||||
const [generating, setGenerating] = useState(false);
|
||||
const [generateError, setGenerateError] = useState("");
|
||||
const [revealToken, setRevealToken] = useState<string | null>(null);
|
||||
const [revokeConfirm, setRevokeConfirm] = useState<string | null>(null);
|
||||
const [copied, setCopied] = useState(false);
|
||||
|
||||
useEffect(() => {
|
||||
fetch("/api/api-keys")
|
||||
.then((r) => {
|
||||
if (!r.ok) throw new Error(`HTTP ${r.status}`);
|
||||
return r.json();
|
||||
})
|
||||
.then((data) => setKeys(data.keys ?? []))
|
||||
.catch(() => setError("Could not load keys. Try closing and reopening this panel."))
|
||||
.finally(() => setLoading(false));
|
||||
}, []);
|
||||
|
||||
const atLimit = keys.length >= MAX_KEYS;
|
||||
|
||||
async function handleGenerate() {
|
||||
if (generating || atLimit) return;
|
||||
setGenerating(true);
|
||||
setGenerateError("");
|
||||
try {
|
||||
const res = await fetch("/api/api-keys", {
|
||||
method: "POST",
|
||||
headers: { "Content-Type": "application/json" },
|
||||
body: JSON.stringify({ name: name.trim() }),
|
||||
});
|
||||
if (res.status === 422) {
|
||||
setGenerateError("Maximum of 3 keys reached");
|
||||
return;
|
||||
}
|
||||
if (!res.ok) {
|
||||
setGenerateError("Failed to generate key. Please try again.");
|
||||
return;
|
||||
}
|
||||
const data = await res.json();
|
||||
const created: KeyRecord = {
|
||||
id: data.key.id,
|
||||
name: data.key.name,
|
||||
prefix: data.key.prefix ?? "",
|
||||
createdAt: data.key.createdAt,
|
||||
lastUsedAt: null,
|
||||
};
|
||||
setKeys((prev) => [created, ...prev]);
|
||||
setRevealToken(data.key.fullToken);
|
||||
setName("");
|
||||
setCopied(false);
|
||||
} catch {
|
||||
setGenerateError("Failed to generate key. Please try again.");
|
||||
} finally {
|
||||
setGenerating(false);
|
||||
}
|
||||
}
|
||||
|
||||
async function handleRevoke(id: string) {
|
||||
const previous = keys;
|
||||
setKeys((prev) => prev.filter((k) => k.id !== id));
|
||||
setRevokeConfirm(null);
|
||||
try {
|
||||
const res = await fetch(`/api/api-keys/${id}`, { method: "DELETE" });
|
||||
if (!res.ok) setKeys(previous);
|
||||
} catch {
|
||||
setKeys(previous);
|
||||
}
|
||||
}
|
||||
|
||||
async function handleCopy() {
|
||||
if (!revealToken) return;
|
||||
try {
|
||||
await navigator.clipboard.writeText(revealToken);
|
||||
setCopied(true);
|
||||
setTimeout(() => setCopied(false), COPIED_RESET_MS);
|
||||
} catch {
|
||||
setGenerateError("Could not copy to clipboard. Select and copy manually.");
|
||||
}
|
||||
}
|
||||
|
||||
return (
|
||||
<div style={{ marginBottom: "var(--space-lg)" }}>
|
||||
<style>{`@keyframes spin { from { transform: rotate(0deg); } to { transform: rotate(360deg); } }`}</style>
|
||||
|
||||
<div style={sectionHeaderStyle}>
|
||||
<KeyRound size={10} style={{ marginRight: 4, verticalAlign: "middle" }} />
|
||||
API & MCP Access
|
||||
</div>
|
||||
<div style={{ ...mutedMicro, marginBottom: "var(--space-md)" }}>
|
||||
Personal bearer keys for authenticating API and MCP requests. Stored server-side.
|
||||
</div>
|
||||
|
||||
{loading && (
|
||||
<div style={{ display: "flex", justifyContent: "center", color: "var(--text-muted)", padding: "var(--space-md) 0" }}>
|
||||
<Loader size={14} style={{ animation: "spin 1s linear infinite" }} />
|
||||
</div>
|
||||
)}
|
||||
|
||||
{!loading && error && <div style={errorText}>{error}</div>}
|
||||
|
||||
{!loading && !error && keys.length === 0 && (
|
||||
<div style={{
|
||||
display: "flex", flexDirection: "column", alignItems: "center",
|
||||
gap: "var(--space-md)", padding: "var(--space-xl) 0",
|
||||
}}
|
||||
>
|
||||
<KeyRound size={24} style={{ color: "var(--text-muted)" }} />
|
||||
<div style={{ fontSize: 14, color: "var(--text-muted)", fontWeight: 400 }}>No API keys yet</div>
|
||||
<div style={mutedMicro}>Generate a key to authenticate API and MCP requests.</div>
|
||||
</div>
|
||||
)}
|
||||
|
||||
{!loading && !error && keys.length > 0 && (
|
||||
<div style={{ marginBottom: "var(--space-md)" }}>
|
||||
{keys.map((k, i) => (
|
||||
<KeyRow
|
||||
key={k.id}
|
||||
record={k}
|
||||
isLast={i === keys.length - 1}
|
||||
confirming={revokeConfirm === k.id}
|
||||
onAskRevoke={() => setRevokeConfirm(k.id)}
|
||||
onCancelRevoke={() => setRevokeConfirm(null)}
|
||||
onConfirmRevoke={() => handleRevoke(k.id)}
|
||||
/>
|
||||
))}
|
||||
</div>
|
||||
)}
|
||||
|
||||
{!loading && !error && (
|
||||
<>
|
||||
<input
|
||||
type="text"
|
||||
value={name}
|
||||
placeholder="Name this key (optional)"
|
||||
onChange={(e) => setName(e.target.value)}
|
||||
style={{ ...inputStyle, fontFamily: "inherit", marginBottom: "var(--space-sm)" }}
|
||||
autoComplete="off"
|
||||
data-lpignore="true"
|
||||
data-form-type="other"
|
||||
spellCheck={false}
|
||||
/>
|
||||
<button
|
||||
type="button"
|
||||
onClick={handleGenerate}
|
||||
disabled={atLimit || generating}
|
||||
style={{
|
||||
...buttonStyle,
|
||||
opacity: atLimit || generating ? 0.4 : 1,
|
||||
cursor: atLimit || generating ? "not-allowed" : "pointer",
|
||||
}}
|
||||
>
|
||||
<Plus size={12} />
|
||||
Generate API Key
|
||||
</button>
|
||||
{atLimit && (
|
||||
<div style={{ fontSize: 10, color: "var(--text-muted)", marginTop: "var(--space-xs)" }}>
|
||||
Maximum of 3 keys reached
|
||||
</div>
|
||||
)}
|
||||
{generateError && (
|
||||
<div style={{ ...errorText, marginTop: "var(--space-xs)" }}>{generateError}</div>
|
||||
)}
|
||||
</>
|
||||
)}
|
||||
|
||||
{revealToken && (
|
||||
<div style={{ marginTop: "var(--space-md)" }}>
|
||||
<div style={{
|
||||
display: "flex", alignItems: "flex-start", gap: "var(--space-xs)",
|
||||
background: "rgba(245,158,11,0.1)", border: "1px solid rgba(245,158,11,0.3)",
|
||||
borderRadius: "var(--radius-sm)", padding: "var(--space-sm) var(--space-md)",
|
||||
marginBottom: "var(--space-sm)",
|
||||
}}
|
||||
>
|
||||
<AlertTriangle size={14} style={{ color: "var(--accent-amber)", flexShrink: 0, marginTop: 1 }} />
|
||||
<span style={{ fontSize: 11, color: "var(--accent-amber)", lineHeight: 1.5 }}>
|
||||
Copy this key now. You won't be able to see it again. Never commit it to source
|
||||
control or share it publicly.
|
||||
</span>
|
||||
</div>
|
||||
<div style={{ display: "flex", gap: "var(--space-xs)" }}>
|
||||
<input
|
||||
type="text"
|
||||
readOnly
|
||||
value={revealToken}
|
||||
style={{ ...inputStyle, fontFamily: "var(--font-mono)" }}
|
||||
autoComplete="off"
|
||||
data-lpignore="true"
|
||||
data-form-type="other"
|
||||
spellCheck={false}
|
||||
/>
|
||||
<button
|
||||
type="button"
|
||||
onClick={handleCopy}
|
||||
style={{ ...buttonStyle, color: copied ? "#22c55e" : "var(--text-primary)" }}
|
||||
>
|
||||
{copied ? "Copied!" : "Copy"}
|
||||
</button>
|
||||
</div>
|
||||
<button
|
||||
type="button"
|
||||
onClick={() => setRevealToken(null)}
|
||||
style={{ ...buttonStyle, width: "100%", justifyContent: "center", marginTop: "var(--space-sm)" }}
|
||||
>
|
||||
Done, I've saved it
|
||||
</button>
|
||||
</div>
|
||||
)}
|
||||
|
||||
<ConnectAgentHelper token={revealToken} />
|
||||
</div>
|
||||
);
|
||||
}
|
||||
@@ -74,6 +74,19 @@
|
||||
margin-top: 3px;
|
||||
}
|
||||
|
||||
/* ─── Local Icon ─────────────────────────────────── */
|
||||
.layer-item__local-icon-wrapper {
|
||||
position: relative;
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
}
|
||||
|
||||
.layer-item__local-icon {
|
||||
color: var(--accent-cyan);
|
||||
flex-shrink: 0;
|
||||
cursor: help;
|
||||
}
|
||||
|
||||
/* ─── Unverified Icon ────────────────────────────── */
|
||||
.layer-item__unverified-icon-wrapper {
|
||||
position: relative;
|
||||
|
||||
@@ -7,7 +7,7 @@
|
||||
* @module src/components/panels
|
||||
*/
|
||||
|
||||
import { ShieldAlert } from "lucide-react";
|
||||
import { ShieldAlert, Wrench } from "lucide-react";
|
||||
import { PluginIcon } from "@/components/common/PluginIcon";
|
||||
import { Tooltip } from "@/components/ui/Tooltip";
|
||||
import { pluginManager } from "@/core/plugins/PluginManager";
|
||||
@@ -27,29 +27,46 @@ const CATEGORY_LABELS: Record<string, string> = {
|
||||
custom: "Custom",
|
||||
};
|
||||
|
||||
// ─── Trust Helpers ──────────────────────────────────────────
|
||||
// ─── Source / Trust Helpers ─────────────────────────────────
|
||||
|
||||
type TrustTier = "built-in" | "verified" | "unverified";
|
||||
|
||||
function getTrust(pluginId: string): TrustTier {
|
||||
function isLocalPlugin(pluginId: string): boolean {
|
||||
const manifest = pluginManager.getManifest(pluginId);
|
||||
return manifest?.trust ?? "unverified";
|
||||
if (!manifest) return true;
|
||||
const entry = manifest.entry ?? "";
|
||||
return entry.startsWith("/plugins-local/") || entry.startsWith("http://localhost") || entry.startsWith("http://127.0.0.1");
|
||||
}
|
||||
|
||||
function TrustIcon({ trust }: { trust: TrustTier }) {
|
||||
if (trust !== "unverified") return null;
|
||||
function TrustIcon({ pluginId, pluginName }: { pluginId: string; pluginName: string }) {
|
||||
if (isLocalPlugin(pluginId)) {
|
||||
return (
|
||||
<Tooltip content={`Local plugin: ${pluginName}`}>
|
||||
<span className="layer-item__local-icon-wrapper">
|
||||
<Wrench
|
||||
size={11}
|
||||
className="layer-item__local-icon"
|
||||
aria-label="Local plugin"
|
||||
/>
|
||||
</span>
|
||||
</Tooltip>
|
||||
);
|
||||
}
|
||||
|
||||
return (
|
||||
<Tooltip content="Unverified plugin, use at your own risk">
|
||||
<span className="layer-item__unverified-icon-wrapper">
|
||||
<ShieldAlert
|
||||
size={12}
|
||||
className="layer-item__unverified-icon"
|
||||
aria-label="Unverified plugin"
|
||||
/>
|
||||
</span>
|
||||
</Tooltip>
|
||||
);
|
||||
const manifest = pluginManager.getManifest(pluginId);
|
||||
if (manifest?.trust === "unverified") {
|
||||
return (
|
||||
<Tooltip content="Unverified plugin, use at your own risk">
|
||||
<span className="layer-item__unverified-icon-wrapper">
|
||||
<ShieldAlert
|
||||
size={12}
|
||||
className="layer-item__unverified-icon"
|
||||
aria-label="Unverified plugin"
|
||||
/>
|
||||
</span>
|
||||
</Tooltip>
|
||||
);
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
// ─── LayerItem Component ────────────────────────────────────
|
||||
@@ -88,8 +105,6 @@ export function LayerItem({
|
||||
onToggle,
|
||||
onSelect,
|
||||
}: LayerItemProps) {
|
||||
const trust = getTrust(plugin.id);
|
||||
|
||||
return (
|
||||
<div
|
||||
className={`layer-item ${isSelected ? "layer-item--selected" : ""}`}
|
||||
@@ -102,7 +117,7 @@ export function LayerItem({
|
||||
<div className="layer-item__info">
|
||||
<div className="layer-item__header">
|
||||
<span className="layer-item__name">{plugin.name}</span>
|
||||
<TrustIcon trust={trust} />
|
||||
<TrustIcon pluginId={plugin.id} pluginName={plugin.name} />
|
||||
</div>
|
||||
<div className="layer-item__desc">{plugin.description}</div>
|
||||
<div className="layer-item__footer">
|
||||
|
||||
@@ -69,6 +69,7 @@
|
||||
.plugin-item__header {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
flex-wrap: wrap;
|
||||
gap: 6px;
|
||||
margin-bottom: 1px;
|
||||
}
|
||||
@@ -77,9 +78,7 @@
|
||||
font-size: 13px;
|
||||
font-weight: 500;
|
||||
color: var(--text-primary);
|
||||
white-space: nowrap;
|
||||
overflow: hidden;
|
||||
text-overflow: ellipsis;
|
||||
word-break: break-word;
|
||||
}
|
||||
|
||||
.plugin-item__version {
|
||||
@@ -184,6 +183,7 @@
|
||||
text-decoration: none;
|
||||
font-size: 13px;
|
||||
font-weight: 500;
|
||||
text-align: center;
|
||||
cursor: pointer;
|
||||
transition: all var(--duration-normal) var(--ease-spring);
|
||||
flex-shrink: 0%;
|
||||
|
||||
@@ -11,12 +11,16 @@
|
||||
import { useState, useEffect, useCallback } from "react";
|
||||
import {
|
||||
Trash2, ExternalLink, RefreshCw, Download, PowerOff, Power,
|
||||
ShieldCheck, ShieldAlert, Shield
|
||||
ShieldCheck, ShieldAlert, HardDrive
|
||||
} from "lucide-react";
|
||||
import { PluginIcon } from "@/components/common/PluginIcon";
|
||||
import type { ComponentType } from "react";
|
||||
import { pluginManager } from "@/core/plugins/PluginManager";
|
||||
import { useStore } from "@/core/state/store";
|
||||
import { getDisabledPluginIds, setPluginDisabled } from "@/core/plugins/pluginPreferences";
|
||||
import { trackEvent } from "@/lib/analytics";
|
||||
import { isPluginInstallEnabled } from "@/core/edition";
|
||||
import type { PluginManifest } from "@/core/plugins/PluginManifest";
|
||||
import "./PluginsTab.css";
|
||||
|
||||
// ─── Types ──────────────────────────────────────────────────
|
||||
@@ -35,9 +39,9 @@ function TrustBadge({ trust }: { trust: string }) {
|
||||
if (trust === "built-in") {
|
||||
return (
|
||||
<span className="trust-badge trust-badge--builtin">
|
||||
<Shield size={9} />
|
||||
<HardDrive size={9} />
|
||||
{' '}
|
||||
Built-in
|
||||
Local
|
||||
</span>
|
||||
);
|
||||
}
|
||||
@@ -96,13 +100,9 @@ function getTrust(record: PluginRecord): string {
|
||||
}
|
||||
}
|
||||
|
||||
function getIcon(record: PluginRecord): string {
|
||||
function getIcon(record: PluginRecord): string | ComponentType<{ size?: number; color?: string }> {
|
||||
const managed = pluginManager.getPlugin(record.pluginId);
|
||||
if (managed) {
|
||||
return typeof managed.plugin.icon === "string"
|
||||
? managed.plugin.icon
|
||||
: "📦";
|
||||
}
|
||||
if (managed) return managed.plugin.icon ?? "📦";
|
||||
try {
|
||||
return JSON.parse(record.config).icon ?? "📦";
|
||||
} catch {
|
||||
@@ -120,6 +120,11 @@ function getName(record: PluginRecord): string {
|
||||
}
|
||||
}
|
||||
|
||||
function getVersion(record: PluginRecord): string {
|
||||
if (record.version !== "built-in") return record.version;
|
||||
return pluginManager.getManifest(record.pluginId)?.version ?? "";
|
||||
}
|
||||
|
||||
// ─── PluginsTab ─────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
@@ -145,7 +150,8 @@ export function PluginsTab() {
|
||||
const dbPlugins: PluginRecord[] = data.plugins ?? [];
|
||||
const dbPluginMap = new Map(dbPlugins.map((p) => [p.pluginId, p]));
|
||||
|
||||
// Add built-in and local plugins that don't have a DB record yet (enabled by default)
|
||||
// Add built-in and local plugins that don't have a DB record yet
|
||||
const disabledIds = getDisabledPluginIds();
|
||||
const allManaged = pluginManager.getAllPlugins();
|
||||
for (const managed of allManaged) {
|
||||
if (!dbPluginMap.has(managed.plugin.id)) {
|
||||
@@ -154,11 +160,16 @@ export function PluginsTab() {
|
||||
version: "built-in",
|
||||
config: "{}",
|
||||
installedAt: new Date().toISOString(),
|
||||
enabled: true
|
||||
enabled: !disabledIds.has(managed.plugin.id)
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
// Apply localStorage disabled state to all records
|
||||
dbPlugins.forEach((p) => {
|
||||
if (disabledIds.has(p.pluginId)) p.enabled = false;
|
||||
});
|
||||
|
||||
setPlugins(dbPlugins);
|
||||
if (typeof data.canManagePlugins === "boolean") {
|
||||
setCanInstall(data.canManagePlugins);
|
||||
@@ -192,32 +203,48 @@ export function PluginsTab() {
|
||||
|
||||
const handleDisable = async (pluginId: string) => {
|
||||
setRemoving(pluginId);
|
||||
try {
|
||||
await fetch("/api/marketplace/disable", {
|
||||
method: "POST",
|
||||
headers: { "Content-Type": "application/json" },
|
||||
body: JSON.stringify({ pluginId }),
|
||||
});
|
||||
trackEvent("plugin-disable", { plugin: pluginId });
|
||||
setNeedsReload(true);
|
||||
} catch {
|
||||
setRemoving(null);
|
||||
}
|
||||
setPluginDisabled(pluginId, true);
|
||||
pluginManager.disablePlugin(pluginId);
|
||||
const state = useStore.getState();
|
||||
state.setLayerEnabled(pluginId, false);
|
||||
state.clearEntities(pluginId);
|
||||
state.setEntityCount(pluginId, 0);
|
||||
if (state.hoveredEntity?.pluginId === pluginId) state.setHoveredEntity(null, null);
|
||||
if (state.selectedEntity?.pluginId === pluginId) state.setSelectedEntity(null);
|
||||
setNeedsReload(true);
|
||||
trackEvent("plugin-disable", { plugin: pluginId });
|
||||
await loadPlugins();
|
||||
setRemoving(null);
|
||||
};
|
||||
|
||||
const handleEnable = async (pluginId: string) => {
|
||||
setRemoving(pluginId);
|
||||
try {
|
||||
await fetch("/api/marketplace/enable", {
|
||||
method: "POST",
|
||||
headers: { "Content-Type": "application/json" },
|
||||
body: JSON.stringify({ pluginId }),
|
||||
});
|
||||
trackEvent("plugin-enable", { plugin: pluginId });
|
||||
setNeedsReload(true);
|
||||
} catch {
|
||||
setRemoving(null);
|
||||
setPluginDisabled(pluginId, false);
|
||||
setNeedsReload(false);
|
||||
|
||||
const alreadyRegistered = pluginManager.getPlugin(pluginId);
|
||||
if (!alreadyRegistered) {
|
||||
// Plugin was disabled at startup — its script was never loaded.
|
||||
// Hot-load the script so it's available; leave the layer toggle off.
|
||||
try {
|
||||
const res = await fetch("/api/marketplace/load");
|
||||
if (res.ok) {
|
||||
const { manifests } = await res.json() as { manifests: PluginManifest[] };
|
||||
const manifest = manifests.find((m) => m.id === pluginId);
|
||||
if (manifest) {
|
||||
await pluginManager.loadFromManifest(manifest);
|
||||
useStore.getState().initLayer(pluginId, false);
|
||||
}
|
||||
}
|
||||
} catch (err) {
|
||||
console.error("[PluginsTab] Failed to hot-load plugin:", pluginId, err);
|
||||
}
|
||||
}
|
||||
// Layer stays off — user controls it via the Data Layers toggle.
|
||||
|
||||
trackEvent("plugin-enable", { plugin: pluginId });
|
||||
await loadPlugins();
|
||||
setRemoving(null);
|
||||
};
|
||||
|
||||
const handleCheckUpdates = async () => {
|
||||
@@ -352,10 +379,12 @@ export function PluginsTab() {
|
||||
<span className="plugin-item__name">
|
||||
{getName(record)}
|
||||
</span>
|
||||
{getVersion(record) && (
|
||||
<span className="plugin-item__version">
|
||||
v
|
||||
{record.version}
|
||||
{getVersion(record)}
|
||||
</span>
|
||||
)}
|
||||
</div>
|
||||
<div className="plugin-item__meta">
|
||||
<TrustBadge trust={getTrust(record)} />
|
||||
@@ -415,10 +444,12 @@ export function PluginsTab() {
|
||||
<span className="plugin-item__name">
|
||||
{getName(record)}
|
||||
</span>
|
||||
{getVersion(record) && (
|
||||
<span className="plugin-item__version">
|
||||
v
|
||||
{record.version}
|
||||
{getVersion(record)}
|
||||
</span>
|
||||
)}
|
||||
</div>
|
||||
<div className="plugin-item__meta">
|
||||
<TrustBadge trust={getTrust(record)} />
|
||||
|
||||
@@ -3,6 +3,7 @@ import type {
|
||||
FilterDefinition,
|
||||
FilterValue,
|
||||
} from "@/core/plugins/PluginTypes";
|
||||
import { matchFilterValue } from "./matchFilterValue";
|
||||
|
||||
/**
|
||||
* Apply active filters to a list of entities.
|
||||
@@ -27,35 +28,10 @@ export function applyFilters(
|
||||
|
||||
const propValue = entity.properties[def.propertyKey];
|
||||
|
||||
if (!matchesFilter(propValue, filterVal)) {
|
||||
if (!matchFilterValue(propValue, filterVal)) {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
return true;
|
||||
});
|
||||
}
|
||||
|
||||
function matchesFilter(propValue: unknown, filter: FilterValue): boolean {
|
||||
switch (filter.type) {
|
||||
case "text": {
|
||||
if (!filter.value) return true; // empty text = no filter
|
||||
const str = String(propValue ?? "").toLowerCase();
|
||||
return str.includes(filter.value.toLowerCase());
|
||||
}
|
||||
case "select": {
|
||||
if (filter.values.length === 0) return true; // no selection = no filter
|
||||
const pVal = String(propValue ?? "").toLowerCase();
|
||||
return filter.values.some((v) => v.toLowerCase() === pVal);
|
||||
}
|
||||
case "range": {
|
||||
const num = Number(propValue ?? 0);
|
||||
if (isNaN(num)) return false;
|
||||
return num >= filter.min && num <= filter.max;
|
||||
}
|
||||
case "boolean": {
|
||||
return Boolean(propValue) === filter.value;
|
||||
}
|
||||
default:
|
||||
return true;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,31 @@
|
||||
import type { FilterValue } from "@/core/plugins/PluginTypes";
|
||||
|
||||
/**
|
||||
* Pure per-value filter matching shared by the client filterEngine and the
|
||||
* server-side search_entities filter (Phase 23, D-08). Behavior must remain
|
||||
* identical to the original inline filterEngine.matchesFilter.
|
||||
*/
|
||||
export function matchFilterValue(propValue: unknown, filter: FilterValue): boolean {
|
||||
switch (filter.type) {
|
||||
case "text": {
|
||||
if (!filter.value) return true; // empty text = no filter
|
||||
const str = String(propValue ?? "").toLowerCase();
|
||||
return str.includes(filter.value.toLowerCase());
|
||||
}
|
||||
case "select": {
|
||||
if (filter.values.length === 0) return true; // no selection = no filter
|
||||
const pVal = String(propValue ?? "").toLowerCase();
|
||||
return filter.values.some((v) => v.toLowerCase() === pVal);
|
||||
}
|
||||
case "range": {
|
||||
const num = Number(propValue ?? 0);
|
||||
if (isNaN(num)) return false;
|
||||
return num >= filter.min && num <= filter.max;
|
||||
}
|
||||
case "boolean": {
|
||||
return Boolean(propValue) === filter.value;
|
||||
}
|
||||
default:
|
||||
return true;
|
||||
}
|
||||
}
|
||||
@@ -34,6 +34,11 @@ import { useSatelliteFrustum } from "./hooks/useSatelliteFrustum";
|
||||
import { useTrailRendering } from "./hooks/useTrailRendering";
|
||||
import { useViewerInitialization } from "./hooks/useViewerInitialization";
|
||||
import { usePersistentDataSync } from "./hooks/usePersistentDataSync";
|
||||
import { useSessionId } from "./hooks/useSessionId";
|
||||
import { useGlobeStateSync } from "./hooks/useGlobeStateSync";
|
||||
import { useGlobeCommandBridge } from "./hooks/useGlobeCommandBridge";
|
||||
import { useMcpCatalogPublisher } from "./hooks/useMcpCatalogPublisher";
|
||||
import { useMcpRelayBridge } from "./hooks/useMcpRelayBridge";
|
||||
|
||||
/** Stable references */
|
||||
const CONTEXT_OPTIONS = { requestWebgl2: true, webgl: { antialias: true } } as const;
|
||||
@@ -120,6 +125,11 @@ enableLighting,
|
||||
|
||||
useSelectionAnchor(viewerRef.current, viewerReady, selectedEntity, lockedEntityId, selectionEntityRef, animatablesMapRef);
|
||||
useCameraSync(viewerRef.current, viewerReady, setCameraPosition, setFps);
|
||||
const sessionId = useSessionId();
|
||||
useGlobeStateSync(sessionId);
|
||||
useGlobeCommandBridge(sessionId);
|
||||
useMcpCatalogPublisher(sessionId);
|
||||
useMcpRelayBridge(sessionId);
|
||||
useCameraActions(viewerRef.current, viewerReady);
|
||||
useEntityRendering(viewerRef.current, viewerReady, visibleEntities, animatablesMapRef, hoveredEntityIdRef, sceneSettings);
|
||||
useModelRendering(viewerRef.current, viewerReady, animatablesMapRef);
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
import { useEffect } from "react";
|
||||
import type { Viewer as CesiumViewer } from "cesium";
|
||||
import {
|
||||
Cartesian3, EasingFunction, Ellipsoid, Math as CesiumMath, Transforms, Matrix4
|
||||
Cartesian3, EasingFunction, Ellipsoid, Math as CesiumMath, Transforms, Matrix4, Rectangle
|
||||
} from "cesium";
|
||||
import { dataBus } from "@/core/data/DataBus";
|
||||
import { showSearchPin } from "./searchPinAnimation";
|
||||
@@ -140,9 +140,21 @@ export function useCameraActions(viewer: CesiumViewer | null, isReady: boolean)
|
||||
}, 50);
|
||||
});
|
||||
|
||||
const unsubFlyToBbox = dataBus.on("cameraFlyToBbox", ({ west, south, east, north }) => {
|
||||
setTimeout(() => {
|
||||
if (!viewer || viewer.isDestroyed()) return;
|
||||
viewer.camera.flyTo({
|
||||
destination: Rectangle.fromDegrees(west, south, east, north),
|
||||
duration: 1.5,
|
||||
easingFunction: EasingFunction.QUINTIC_IN_OUT,
|
||||
});
|
||||
}, 50);
|
||||
});
|
||||
|
||||
return () => {
|
||||
unsubFace();
|
||||
unsubGoTo();
|
||||
unsubFlyToBbox();
|
||||
};
|
||||
}, [viewer, isReady]);
|
||||
}
|
||||
@@ -0,0 +1,249 @@
|
||||
/**
|
||||
* Contract tests for useGlobeCommandBridge (Phase 19b Wave 0).
|
||||
*
|
||||
* BRIDGE-01 through BRIDGE-07 are INTENTIONALLY RED in Wave 0 because the hook
|
||||
* still uses setInterval + pollOnce. Wave 1 rewrites the hook to use EventSource.
|
||||
*
|
||||
* BRIDGE-01 Hook opens EventSource to /api/globe/commands/stream?sessionId=... on mount
|
||||
* BRIDGE-02 pan command dispatched via onmessage -> dataBus.emit("cameraGoTo", ...)
|
||||
* BRIDGE-03 toggleLayer command dispatched via onmessage -> Zustand setLayerEnabled
|
||||
* BRIDGE-04 Unknown command type via onmessage -> nothing dispatched
|
||||
* BRIDGE-05 Empty sessionId -> EventSource never created
|
||||
* BRIDGE-06 Unmount -> EventSource.close() called
|
||||
* BRIDGE-07 onerror firing -> no throw
|
||||
*/
|
||||
|
||||
import { describe, it, expect, vi, beforeEach } from "vitest";
|
||||
import { renderHook, act } from "@testing-library/react";
|
||||
import { useGlobeCommandBridge } from "./useGlobeCommandBridge";
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Mock DataBus
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
const { mockEmit } = vi.hoisted(() => ({
|
||||
mockEmit: vi.fn(),
|
||||
}));
|
||||
|
||||
vi.mock("@/core/data/DataBus", () => ({
|
||||
dataBus: {
|
||||
emit: mockEmit,
|
||||
},
|
||||
}));
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Mock Zustand store
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
const {
|
||||
mockSetLayerEnabled,
|
||||
mockToggleLayer,
|
||||
mockSetTimeWindow,
|
||||
mockSetPlaybackMode,
|
||||
mockSetCurrentTime,
|
||||
} = vi.hoisted(() => ({
|
||||
mockSetLayerEnabled: vi.fn(),
|
||||
mockToggleLayer: vi.fn(),
|
||||
mockSetTimeWindow: vi.fn(),
|
||||
mockSetPlaybackMode: vi.fn(),
|
||||
mockSetCurrentTime: vi.fn(),
|
||||
}));
|
||||
|
||||
vi.mock("@/core/state/store", () => ({
|
||||
useStore: {
|
||||
getState: vi.fn(() => ({
|
||||
setLayerEnabled: mockSetLayerEnabled,
|
||||
toggleLayer: mockToggleLayer,
|
||||
setTimeWindow: mockSetTimeWindow,
|
||||
setPlaybackMode: mockSetPlaybackMode,
|
||||
setCurrentTime: mockSetCurrentTime,
|
||||
layers: {},
|
||||
})),
|
||||
subscribe: vi.fn(() => () => undefined),
|
||||
},
|
||||
}));
|
||||
|
||||
import { useStore } from "@/core/state/store";
|
||||
|
||||
const mockedUseStore = useStore as unknown as {
|
||||
getState: ReturnType<typeof vi.fn>;
|
||||
subscribe: ReturnType<typeof vi.fn>;
|
||||
};
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// MockEventSource
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
let mockEs: MockEventSource;
|
||||
|
||||
class MockEventSource {
|
||||
url: string;
|
||||
onmessage: ((ev: MessageEvent) => void) | null = null;
|
||||
onerror: ((ev: Event) => void) | null = null;
|
||||
close = vi.fn();
|
||||
|
||||
constructor(url: string) {
|
||||
this.url = url;
|
||||
// eslint-disable-next-line @typescript-eslint/no-this-alias
|
||||
mockEs = this;
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Setup
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
beforeEach(() => {
|
||||
vi.resetAllMocks();
|
||||
|
||||
// Install MockEventSource as the global before each test
|
||||
global.EventSource = MockEventSource as unknown as typeof EventSource;
|
||||
|
||||
// Restore getState return value after vi.resetAllMocks() wipes call history
|
||||
mockedUseStore.getState.mockReturnValue({
|
||||
setLayerEnabled: mockSetLayerEnabled,
|
||||
toggleLayer: mockToggleLayer,
|
||||
setTimeWindow: mockSetTimeWindow,
|
||||
setPlaybackMode: mockSetPlaybackMode,
|
||||
setCurrentTime: mockSetCurrentTime,
|
||||
layers: {},
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// BRIDGE-01: EventSource connection on mount
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("useGlobeCommandBridge EventSource connection (BRIDGE-01)", () => {
|
||||
it("opens an EventSource to /api/globe/commands/stream?sessionId=... on mount", () => {
|
||||
// Track construction via the mockEs reference populated by MockEventSource constructor
|
||||
renderHook(() => useGlobeCommandBridge("sess-1"));
|
||||
|
||||
// mockEs is set by the MockEventSource constructor -- if hook never calls new EventSource,
|
||||
// mockEs will be undefined and these assertions fail (correct RED state).
|
||||
expect(mockEs).toBeDefined();
|
||||
expect(mockEs.url).toContain("/api/globe/commands/stream");
|
||||
expect(mockEs.url).toContain("sessionId=sess-1");
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// BRIDGE-02: pan command via onmessage -> cameraGoTo
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("useGlobeCommandBridge pan dispatch (BRIDGE-02)", () => {
|
||||
it("emits cameraGoTo when a pan command arrives via onmessage", () => {
|
||||
renderHook(() => useGlobeCommandBridge("sess-1"));
|
||||
|
||||
act(() => {
|
||||
mockEs.onmessage?.(
|
||||
new MessageEvent("message", {
|
||||
data: JSON.stringify({
|
||||
commands: [{ type: "pan", lat: 1, lon: 2, alt: 3 }],
|
||||
}),
|
||||
}),
|
||||
);
|
||||
});
|
||||
|
||||
expect(mockEmit).toHaveBeenCalledWith(
|
||||
"cameraGoTo",
|
||||
expect.objectContaining({ lat: 1, lon: 2, alt: 3 }),
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// BRIDGE-03: toggleLayer command via onmessage -> Zustand action
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("useGlobeCommandBridge toggleLayer dispatch (BRIDGE-03)", () => {
|
||||
it("calls toggleLayer when a toggleLayer command arrives via onmessage", () => {
|
||||
renderHook(() => useGlobeCommandBridge("sess-1"));
|
||||
|
||||
act(() => {
|
||||
mockEs.onmessage?.(
|
||||
new MessageEvent("message", {
|
||||
data: JSON.stringify({
|
||||
commands: [{ type: "toggleLayer", layerId: "ais" }],
|
||||
}),
|
||||
}),
|
||||
);
|
||||
});
|
||||
|
||||
const anyLayerAction =
|
||||
mockSetLayerEnabled.mock.calls.length > 0 ||
|
||||
mockToggleLayer.mock.calls.length > 0;
|
||||
expect(anyLayerAction).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// BRIDGE-04: unknown command type -> nothing dispatched
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("useGlobeCommandBridge invalid command filtering (BRIDGE-04)", () => {
|
||||
it("does not dispatch anything for an unknown command type arriving via onmessage", () => {
|
||||
renderHook(() => useGlobeCommandBridge("sess-1"));
|
||||
|
||||
act(() => {
|
||||
mockEs.onmessage?.(
|
||||
new MessageEvent("message", {
|
||||
data: JSON.stringify({
|
||||
commands: [{ type: "invalidCommand", foo: "bar" }],
|
||||
}),
|
||||
}),
|
||||
);
|
||||
});
|
||||
|
||||
expect(mockEmit).not.toHaveBeenCalled();
|
||||
expect(mockSetLayerEnabled).not.toHaveBeenCalled();
|
||||
expect(mockToggleLayer).not.toHaveBeenCalled();
|
||||
expect(mockSetTimeWindow).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// BRIDGE-05: empty sessionId -> EventSource never created
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("useGlobeCommandBridge empty sessionId no-op (BRIDGE-05)", () => {
|
||||
it("never creates an EventSource when sessionId is empty string", () => {
|
||||
// Reset mockEs -- if hook creates an EventSource, MockEventSource constructor sets it
|
||||
(mockEs as MockEventSource | undefined) = undefined as unknown as MockEventSource;
|
||||
|
||||
renderHook(() => useGlobeCommandBridge(""));
|
||||
|
||||
// If EventSource was constructed, mockEs would be set
|
||||
expect(mockEs as MockEventSource | undefined).toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// BRIDGE-06: unmount -> EventSource.close() called
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("useGlobeCommandBridge unmount cleanup (BRIDGE-06)", () => {
|
||||
it("calls EventSource.close() on unmount", () => {
|
||||
const { unmount } = renderHook(() => useGlobeCommandBridge("sess-1"));
|
||||
|
||||
unmount();
|
||||
|
||||
expect(mockEs.close).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// BRIDGE-07: onerror fires -> no throw
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("useGlobeCommandBridge onerror resilience (BRIDGE-07)", () => {
|
||||
it("does not throw when onerror fires", () => {
|
||||
renderHook(() => useGlobeCommandBridge("sess-1"));
|
||||
|
||||
act(() => {
|
||||
mockEs.onerror?.(new Event("error"));
|
||||
});
|
||||
|
||||
// Reaching here without an unhandled exception is the assertion
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,143 @@
|
||||
import { useEffect } from "react";
|
||||
import { dataBus } from "@/core/data/DataBus";
|
||||
import { useStore } from "@/core/state/store";
|
||||
import { isValidGlobeCommand } from "@/core/globe/types/GlobeCommand";
|
||||
import type { GlobeCommand } from "@/core/globe/types/GlobeCommand";
|
||||
|
||||
function dispatchCommand(cmd: GlobeCommand): void {
|
||||
switch (cmd.type) {
|
||||
case "pan":
|
||||
dataBus.emit("cameraGoTo", {
|
||||
lat: cmd.lat,
|
||||
lon: cmd.lon,
|
||||
alt: cmd.alt,
|
||||
// cameraGoTo exposes maxPitch (a clamp), not a target pitch angle,
|
||||
// so cmd.pitch is intentionally not forwarded here.
|
||||
...(cmd.heading !== undefined ? { heading: cmd.heading } : {}),
|
||||
});
|
||||
break;
|
||||
|
||||
case "flyTo":
|
||||
if (cmd.bbox) {
|
||||
const [west, south, east, north] = cmd.bbox;
|
||||
dataBus.emit("cameraFlyToBbox", { west, south, east, north });
|
||||
} else {
|
||||
dataBus.emit("cameraGoTo", {
|
||||
lat: cmd.lat,
|
||||
lon: cmd.lng, // flyTo uses "lng"; cameraGoTo expects "lon" -- explicit mapping per D-03
|
||||
alt: cmd.alt ?? 15_000,
|
||||
});
|
||||
}
|
||||
break;
|
||||
|
||||
case "focusEntity":
|
||||
if (cmd.lat !== undefined && cmd.lon !== undefined) {
|
||||
dataBus.emit("cameraGoTo", {
|
||||
lat: cmd.lat,
|
||||
lon: cmd.lon,
|
||||
alt: 0,
|
||||
});
|
||||
} else if (cmd.entityId !== undefined) {
|
||||
// Entity-id-only resolution is not yet wired to the entity registry.
|
||||
// Provide lat/lon alongside entityId to trigger a camera move.
|
||||
console.warn(
|
||||
"[useGlobeCommandBridge] focusEntity by id not yet supported; provide lat/lon",
|
||||
cmd.entityId,
|
||||
);
|
||||
}
|
||||
break;
|
||||
|
||||
case "toggleLayer": {
|
||||
const state = useStore.getState();
|
||||
if (cmd.enabled !== undefined) {
|
||||
state.setLayerEnabled(cmd.layerId, cmd.enabled);
|
||||
} else {
|
||||
state.toggleLayer(cmd.layerId);
|
||||
}
|
||||
break;
|
||||
}
|
||||
|
||||
case "setTimeline": {
|
||||
const state = useStore.getState();
|
||||
if (cmd.timeWindow !== undefined) {
|
||||
// cmd.timeWindow is narrowed to TimeWindowLiteral by isValidGlobeCommand.
|
||||
state.setTimeWindow(cmd.timeWindow);
|
||||
}
|
||||
if (cmd.isPlaybackMode !== undefined) {
|
||||
state.setPlaybackMode(cmd.isPlaybackMode);
|
||||
}
|
||||
if (cmd.currentTime !== undefined) {
|
||||
const d = new Date(cmd.currentTime);
|
||||
if (!Number.isNaN(d.getTime())) {
|
||||
state.setCurrentTime(d);
|
||||
}
|
||||
}
|
||||
break;
|
||||
}
|
||||
|
||||
case "setFilter": {
|
||||
const state = useStore.getState();
|
||||
for (const [filterId, value] of Object.entries(cmd.filters)) {
|
||||
state.setFilter(cmd.pluginId, filterId, value);
|
||||
}
|
||||
break;
|
||||
}
|
||||
|
||||
case "clearFilter": {
|
||||
const state = useStore.getState();
|
||||
if (cmd.pluginId !== undefined) {
|
||||
state.clearFilters(cmd.pluginId);
|
||||
} else {
|
||||
state.clearAllFilters();
|
||||
}
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
export function useGlobeCommandBridge(sessionId: string): void {
|
||||
useEffect(() => {
|
||||
if (!sessionId) return;
|
||||
|
||||
const es = new EventSource(
|
||||
`/api/globe/commands/stream?sessionId=${encodeURIComponent(sessionId)}`,
|
||||
);
|
||||
|
||||
es.onmessage = (event: MessageEvent) => {
|
||||
try {
|
||||
const parsed: unknown = JSON.parse(event.data as string);
|
||||
if (
|
||||
parsed !== null &&
|
||||
typeof parsed === "object" &&
|
||||
"commands" in parsed &&
|
||||
Array.isArray((parsed as { commands: unknown }).commands)
|
||||
) {
|
||||
(parsed as { commands: unknown[] }).commands
|
||||
.filter(isValidGlobeCommand)
|
||||
.forEach(dispatchCommand);
|
||||
}
|
||||
} catch (err) {
|
||||
console.error("[useGlobeCommandBridge] Failed to parse SSE message:", err);
|
||||
}
|
||||
};
|
||||
|
||||
es.onerror = () => {
|
||||
// onerror fires on the normal stream close too: the server ends each
|
||||
// stream at MAX_DURATION_MS (~16s), after which EventSource transparently
|
||||
// reconnects (readyState === CONNECTING). Only a terminal failure leaves
|
||||
// readyState === CLOSED -- e.g. a 401 because EventSource authenticates via
|
||||
// the NextAuth session cookie (it cannot send a Bearer header), so an
|
||||
// unauthenticated tab fails permanently rather than reconnecting.
|
||||
if (es.readyState === EventSource.CLOSED) {
|
||||
console.error(
|
||||
"[useGlobeCommandBridge] SSE stream closed without retry -- " +
|
||||
"is this tab signed in? EventSource auths via session cookie, not Bearer.",
|
||||
);
|
||||
}
|
||||
};
|
||||
|
||||
return () => {
|
||||
es.close();
|
||||
};
|
||||
}, [sessionId]);
|
||||
}
|
||||
@@ -0,0 +1,125 @@
|
||||
import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
|
||||
import { renderHook, act } from "@testing-library/react";
|
||||
import { useGlobeStateSync } from "./useGlobeStateSync";
|
||||
|
||||
vi.mock("@/lib/globeState", () => ({
|
||||
buildGlobeSnapshot: vi.fn(() => ({ marker: true })),
|
||||
}));
|
||||
|
||||
vi.mock("@/core/state/store", () => {
|
||||
let listener: (() => void) | null = null;
|
||||
return {
|
||||
useStore: {
|
||||
getState: vi.fn(() => ({})),
|
||||
subscribe: vi.fn((cb: () => void) => {
|
||||
listener = cb;
|
||||
// Return unsubscribe function
|
||||
return () => { listener = null; };
|
||||
}),
|
||||
// Expose for triggering store changes in tests
|
||||
__triggerChange: () => { if (listener) listener(); },
|
||||
},
|
||||
};
|
||||
});
|
||||
|
||||
// Retrieve the mocked store for use in tests
|
||||
import { useStore } from "@/core/state/store";
|
||||
const mockStore = useStore as unknown as {
|
||||
getState: ReturnType<typeof vi.fn>;
|
||||
subscribe: ReturnType<typeof vi.fn>;
|
||||
__triggerChange: () => void;
|
||||
};
|
||||
|
||||
describe("useGlobeStateSync", () => {
|
||||
beforeEach(() => {
|
||||
vi.useFakeTimers();
|
||||
global.fetch = vi.fn().mockResolvedValue({ ok: true });
|
||||
vi.clearAllMocks();
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
vi.useRealTimers();
|
||||
vi.restoreAllMocks();
|
||||
});
|
||||
|
||||
it("performs no fetch when sessionId is empty (no-op gate)", async () => {
|
||||
renderHook(() => useGlobeStateSync(""));
|
||||
await act(async () => {
|
||||
vi.advanceTimersByTime(15_000);
|
||||
});
|
||||
|
||||
expect(fetch).not.toHaveBeenCalled();
|
||||
expect(mockStore.subscribe).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("subscribes to the store and POSTs to /api/globe/state after 500ms debounce", async () => {
|
||||
renderHook(() => useGlobeStateSync("s1"));
|
||||
|
||||
// Drain the immediate initial push that fires on mount before asserting debounce behavior.
|
||||
await act(async () => {});
|
||||
(fetch as ReturnType<typeof vi.fn>).mockClear();
|
||||
|
||||
// Trigger a store change
|
||||
act(() => { mockStore.__triggerChange(); });
|
||||
|
||||
// Before debounce expires: no fetch yet
|
||||
act(() => { vi.advanceTimersByTime(400); });
|
||||
expect(fetch).not.toHaveBeenCalled();
|
||||
|
||||
// After debounce expires: one fetch
|
||||
await act(async () => { vi.advanceTimersByTime(200); });
|
||||
expect(fetch).toHaveBeenCalledOnce();
|
||||
|
||||
const [url, init] = (fetch as ReturnType<typeof vi.fn>).mock.calls[0] as [string, RequestInit];
|
||||
expect(url).toBe("/api/globe/state");
|
||||
expect(init.method).toBe("POST");
|
||||
expect(JSON.parse(init.body as string)).toMatchObject({ sessionId: "s1" });
|
||||
});
|
||||
|
||||
it("collapses multiple rapid changes within 500ms into a single fetch (debounce)", async () => {
|
||||
renderHook(() => useGlobeStateSync("s1"));
|
||||
|
||||
// Drain the immediate initial push that fires on mount before asserting debounce behavior.
|
||||
await act(async () => {});
|
||||
(fetch as ReturnType<typeof vi.fn>).mockClear();
|
||||
|
||||
// Trigger several rapid store changes
|
||||
act(() => { mockStore.__triggerChange(); });
|
||||
act(() => { vi.advanceTimersByTime(100); });
|
||||
act(() => { mockStore.__triggerChange(); });
|
||||
act(() => { vi.advanceTimersByTime(100); });
|
||||
act(() => { mockStore.__triggerChange(); });
|
||||
|
||||
// Advance past the debounce window
|
||||
await act(async () => { vi.advanceTimersByTime(600); });
|
||||
|
||||
// Despite 3 change events, only 1 fetch
|
||||
expect(fetch).toHaveBeenCalledOnce();
|
||||
});
|
||||
|
||||
it("fires a heartbeat fetch after 10s even without store changes", async () => {
|
||||
renderHook(() => useGlobeStateSync("s1"));
|
||||
|
||||
// Drain the immediate initial push that fires on mount before asserting heartbeat behavior.
|
||||
await act(async () => {});
|
||||
(fetch as ReturnType<typeof vi.fn>).mockClear();
|
||||
|
||||
// No store changes — only advance 10s for the heartbeat
|
||||
await act(async () => { vi.advanceTimersByTime(10_000); });
|
||||
|
||||
expect(fetch).toHaveBeenCalledOnce();
|
||||
const [url] = (fetch as ReturnType<typeof vi.fn>).mock.calls[0] as [string];
|
||||
expect(url).toBe("/api/globe/state");
|
||||
});
|
||||
|
||||
it("does not throw when fetch rejects (fire-and-forget)", async () => {
|
||||
(global.fetch as ReturnType<typeof vi.fn>).mockRejectedValue(new Error("Network error"));
|
||||
|
||||
// If the hook throws, renderHook itself would throw and the test would fail.
|
||||
// Completing without error proves fire-and-forget is working correctly.
|
||||
renderHook(() => useGlobeStateSync("s1"));
|
||||
|
||||
// Trigger via heartbeat — rejected fetch must not propagate as an unhandled rejection
|
||||
await act(async () => { vi.advanceTimersByTime(10_000); });
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,60 @@
|
||||
import { useEffect, useRef } from "react";
|
||||
import { useStore } from "@/core/state/store";
|
||||
import { buildGlobeSnapshot } from "@/lib/globeState";
|
||||
|
||||
const STATE_SYNC_DEBOUNCE_MS = 500;
|
||||
const STATE_SYNC_HEARTBEAT_MS = 10_000;
|
||||
|
||||
async function pushState(sessionId: string): Promise<void> {
|
||||
const snapshot = buildGlobeSnapshot(useStore.getState());
|
||||
try {
|
||||
await fetch("/api/globe/state", {
|
||||
method: "POST",
|
||||
headers: { "Content-Type": "application/json" },
|
||||
body: JSON.stringify({ sessionId, snapshot }),
|
||||
});
|
||||
} catch (err) {
|
||||
console.error("[useGlobeStateSync] Failed to push globe state:", err);
|
||||
}
|
||||
}
|
||||
|
||||
export function useGlobeStateSync(sessionId: string): void {
|
||||
const debounceRef = useRef<ReturnType<typeof setTimeout> | null>(null);
|
||||
const heartbeatRef = useRef<ReturnType<typeof setInterval> | null>(null);
|
||||
const initialPushDoneRef = useRef(false);
|
||||
|
||||
// Fire one immediate push as soon as a valid sessionId is available so that
|
||||
// MCP clients calling resolveActiveSessionId don't see a null ZSET entry
|
||||
// during the window before the first store change or heartbeat fires.
|
||||
useEffect(() => {
|
||||
if (!sessionId) return;
|
||||
if (initialPushDoneRef.current) return;
|
||||
initialPushDoneRef.current = true;
|
||||
void pushState(sessionId);
|
||||
}, [sessionId]);
|
||||
|
||||
useEffect(() => {
|
||||
// No-op until we have a stable session id (pre-mount or SSR)
|
||||
if (!sessionId) return;
|
||||
|
||||
const schedulePush = () => {
|
||||
if (debounceRef.current) clearTimeout(debounceRef.current);
|
||||
debounceRef.current = setTimeout(() => {
|
||||
void pushState(sessionId);
|
||||
}, STATE_SYNC_DEBOUNCE_MS);
|
||||
};
|
||||
|
||||
const unsubscribe = useStore.subscribe(schedulePush);
|
||||
|
||||
// Heartbeat: keeps the TTL and ZSET score fresh even when the camera is idle
|
||||
heartbeatRef.current = setInterval(() => {
|
||||
void pushState(sessionId);
|
||||
}, STATE_SYNC_HEARTBEAT_MS);
|
||||
|
||||
return () => {
|
||||
if (debounceRef.current) clearTimeout(debounceRef.current);
|
||||
if (heartbeatRef.current) clearInterval(heartbeatRef.current);
|
||||
unsubscribe();
|
||||
};
|
||||
}, [sessionId]);
|
||||
}
|
||||
@@ -0,0 +1,167 @@
|
||||
/**
|
||||
* @file useMcpCatalogPublisher.ts
|
||||
* @description Browser hook that publishes the loaded plugins' MCP tools and
|
||||
* capabilities to the per-session catalog on the server (Phase 21 Wave 2).
|
||||
*
|
||||
* The hook reads loaded+enabled plugins from pluginManager, collects their
|
||||
* mcpTools + mcpCapabilities from their loaded manifests, and POSTs to
|
||||
* POST /api/mcp/catalog on mount, when the plugin set changes, and
|
||||
* periodically to keep the catalog TTL fresh.
|
||||
*
|
||||
* Design constraints:
|
||||
* - No-op when no plugins declare mcpTools.
|
||||
* - Identity comes from the existing session cookie (NextAuth) -- the browser
|
||||
* does NOT invent or pass a userId; the server resolves identity from the
|
||||
* session cookie or Bearer token attached to the fetch.
|
||||
* - sessionId is the tab-scoped UUID from the session heartbeat (passed in
|
||||
* as a prop so this hook stays pure and testable).
|
||||
* - Mirrors useGlobeCommandBridge.ts: effect + interval + cleanup.
|
||||
* - console.error in catch only. No any. No ts-ignore.
|
||||
*/
|
||||
|
||||
import { useEffect, useRef } from "react";
|
||||
import { pluginManager } from "@/core/plugins/PluginManager";
|
||||
import { getNamespacedTools } from "@/lib/mcp/pluginTools";
|
||||
import type { PluginToolsEntry } from "@/lib/mcp/pluginTools";
|
||||
import type { CatalogTool } from "@/lib/mcpSessionCatalog";
|
||||
import type { FilterDefinition } from "@/core/plugins/PluginTypes";
|
||||
|
||||
/** Re-publish interval in ms -- mirrors the 19a session-heartbeat cadence. */
|
||||
const PUBLISH_INTERVAL_MS = 30_000;
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Catalog collection helper
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
interface CatalogPayload {
|
||||
sessionId?: string;
|
||||
tools: CatalogTool[];
|
||||
capabilities: string[];
|
||||
filterDefinitions?: Record<string, FilterDefinition[]>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Collects mcpTools, mcpCapabilities, and declared filterDefinitions from all
|
||||
* loaded plugins. Only includes plugins whose manifests declare at least one
|
||||
* mcpTool (tools); filterDefinitions includes only plugins that returned a
|
||||
* non-empty array from getFilterDefinitions() (D-05).
|
||||
*/
|
||||
function collectCatalog(): {
|
||||
tools: CatalogTool[];
|
||||
capabilities: string[];
|
||||
filterDefinitions: Record<string, FilterDefinition[]>;
|
||||
} {
|
||||
const allPlugins = pluginManager.getAllPlugins();
|
||||
|
||||
const entries: PluginToolsEntry[] = allPlugins.flatMap((managed) => {
|
||||
const pluginId = managed.plugin.id;
|
||||
const manifest = pluginManager.getManifest(pluginId);
|
||||
if (!manifest) return [];
|
||||
return [
|
||||
{
|
||||
pluginId,
|
||||
mcpTools: manifest.mcpTools,
|
||||
mcpCapabilities: manifest.mcpCapabilities,
|
||||
},
|
||||
];
|
||||
});
|
||||
|
||||
const namespacedTools = getNamespacedTools(entries);
|
||||
|
||||
const capabilitySet = new Set<string>();
|
||||
const tools: CatalogTool[] = namespacedTools.map((nt) => {
|
||||
for (const cap of nt.capabilities) {
|
||||
capabilitySet.add(cap);
|
||||
}
|
||||
return {
|
||||
namespacedName: nt.namespacedName,
|
||||
pluginId: nt.pluginId,
|
||||
description: nt.description,
|
||||
inputSchema: nt.inputSchema,
|
||||
mcpCapabilities: nt.capabilities.length > 0 ? nt.capabilities : undefined,
|
||||
};
|
||||
});
|
||||
|
||||
// Collect declared filterable fields from each loaded plugin instance.
|
||||
// Only include plugins that returned a non-empty definitions array (D-05).
|
||||
const filterDefinitions: Record<string, FilterDefinition[]> = {};
|
||||
for (const managed of allPlugins) {
|
||||
const defs = managed.plugin.getFilterDefinitions?.();
|
||||
if (defs && defs.length > 0) {
|
||||
filterDefinitions[managed.plugin.id] = defs;
|
||||
}
|
||||
}
|
||||
|
||||
return { tools, capabilities: Array.from(capabilitySet), filterDefinitions };
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Publish helper
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
async function publishCatalog(
|
||||
sessionId: string,
|
||||
active: { current: boolean },
|
||||
): Promise<void> {
|
||||
const { tools, capabilities, filterDefinitions } = collectCatalog();
|
||||
|
||||
// No-op only when nothing is publishable: no MCP tools AND no declared
|
||||
// filters. A filter-only plugin still publishes so get_plugin_filters works.
|
||||
if (tools.length === 0 && Object.keys(filterDefinitions).length === 0) return;
|
||||
|
||||
if (!active.current) return;
|
||||
|
||||
const payload: CatalogPayload = {
|
||||
sessionId,
|
||||
tools,
|
||||
capabilities,
|
||||
...(Object.keys(filterDefinitions).length > 0 && { filterDefinitions }),
|
||||
};
|
||||
|
||||
try {
|
||||
const res = await fetch("/api/mcp/catalog", {
|
||||
method: "POST",
|
||||
headers: { "Content-Type": "application/json" },
|
||||
body: JSON.stringify(payload),
|
||||
});
|
||||
|
||||
if (!res.ok && active.current) {
|
||||
console.error("[useMcpCatalogPublisher] catalog POST failed:", res.status);
|
||||
}
|
||||
} catch (err) {
|
||||
console.error("[useMcpCatalogPublisher] catalog POST error:", err);
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Hook
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Publishes the loaded plugins' MCP catalog to the server.
|
||||
*
|
||||
* @param sessionId - Tab-scoped UUID from the session heartbeat (from useSessionId).
|
||||
* Pass an empty string or undefined to suppress publishing.
|
||||
*/
|
||||
export function useMcpCatalogPublisher(sessionId: string): void {
|
||||
const activeRef = useRef(false);
|
||||
|
||||
useEffect(() => {
|
||||
if (!sessionId) return;
|
||||
|
||||
activeRef.current = true;
|
||||
|
||||
// Publish immediately on mount
|
||||
void publishCatalog(sessionId, activeRef);
|
||||
|
||||
// Re-publish periodically to keep TTL fresh
|
||||
const intervalId = setInterval(() => {
|
||||
void publishCatalog(sessionId, activeRef);
|
||||
}, PUBLISH_INTERVAL_MS);
|
||||
|
||||
return () => {
|
||||
activeRef.current = false;
|
||||
clearInterval(intervalId);
|
||||
};
|
||||
}, [sessionId]);
|
||||
}
|
||||
@@ -0,0 +1,199 @@
|
||||
/**
|
||||
* @file useMcpRelayBridge.ts
|
||||
* @description Browser-side bridge that relays plugin tool invocations (Phase 21 Wave 3 -- PLUG-03).
|
||||
*
|
||||
* The bridge polls GET /api/mcp/invocations on a ~1500ms interval (mirroring
|
||||
* useGlobeCommandBridge). For each pending invocation it:
|
||||
* 1. Strips the {pluginId}__ namespace prefix to get the raw tool name.
|
||||
* 2. Resolves the owning plugin from pluginManager.
|
||||
* 3. Calls plugin.executeMcpTool(rawToolName, args).
|
||||
* 4. POSTs { requestId, sessionId, result } to /api/mcp/results.
|
||||
*
|
||||
* On plugin error or missing executeMcpTool, posts a sanitized error result so
|
||||
* the server-side blpop resolves instead of timing out (SEC-02).
|
||||
*
|
||||
* Design mirrors useGlobeCommandBridge.ts:
|
||||
* - effect + interval + cleanup
|
||||
* - inFlightRef prevents overlapping polls
|
||||
* - activeRef prevents state updates after unmount
|
||||
* - console.error in catch only
|
||||
* - No any, no ts-ignore
|
||||
*/
|
||||
|
||||
import { useEffect, useRef } from "react";
|
||||
import { pluginManager } from "@/core/plugins/PluginManager";
|
||||
|
||||
const POLL_INTERVAL_MS = 1500;
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Invocation shape (matches ToolInvocation in mcpRelay.ts)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
interface ToolInvocation {
|
||||
requestId: string;
|
||||
tool: string;
|
||||
args: Record<string, unknown>;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Poll helper
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
async function pollOnce(sessionId: string, active: { current: boolean }): Promise<void> {
|
||||
let invocations: ToolInvocation[] = [];
|
||||
|
||||
try {
|
||||
const res = await fetch(`/api/mcp/invocations?sessionId=${encodeURIComponent(sessionId)}`);
|
||||
if (!res.ok || !active.current) return;
|
||||
|
||||
const body = (await res.json()) as { invocations: unknown[] };
|
||||
invocations = (body.invocations ?? []).filter(isToolInvocation);
|
||||
} catch (err) {
|
||||
console.error("[useMcpRelayBridge] invocations poll failed:", err);
|
||||
return;
|
||||
}
|
||||
|
||||
if (!active.current || invocations.length === 0) return;
|
||||
|
||||
// Process each invocation -- errors post a sanitized result so the server unblocks.
|
||||
for (const inv of invocations) {
|
||||
if (!active.current) break;
|
||||
await dispatchInvocation(inv, sessionId, active);
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Dispatch a single invocation
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
async function dispatchInvocation(
|
||||
inv: ToolInvocation,
|
||||
sessionId: string,
|
||||
active: { current: boolean },
|
||||
): Promise<void> {
|
||||
// Strip the {pluginId}__ namespace to get both the pluginId and raw tool name.
|
||||
const separatorIdx = inv.tool.indexOf("__");
|
||||
if (separatorIdx === -1) {
|
||||
await postResult(inv.requestId, sessionId, {
|
||||
error: `Malformed tool name (no namespace separator): ${inv.tool}`,
|
||||
}, active);
|
||||
return;
|
||||
}
|
||||
|
||||
const pluginId = inv.tool.slice(0, separatorIdx);
|
||||
const rawToolName = inv.tool.slice(separatorIdx + 2);
|
||||
|
||||
// Resolve the owning plugin from the plugin manager.
|
||||
const managed = pluginManager.getPlugin(pluginId);
|
||||
if (!managed) {
|
||||
await postResult(inv.requestId, sessionId, {
|
||||
error: `Plugin not found: ${pluginId}`,
|
||||
}, active);
|
||||
return;
|
||||
}
|
||||
|
||||
const plugin = managed.plugin;
|
||||
|
||||
// Check that the plugin implements executeMcpTool.
|
||||
if (typeof plugin.executeMcpTool !== "function") {
|
||||
await postResult(inv.requestId, sessionId, {
|
||||
error: `Plugin ${pluginId} does not implement executeMcpTool`,
|
||||
}, active);
|
||||
return;
|
||||
}
|
||||
|
||||
try {
|
||||
const result = await plugin.executeMcpTool(rawToolName, inv.args);
|
||||
if (active.current) {
|
||||
await postResult(inv.requestId, sessionId, result, active);
|
||||
}
|
||||
} catch (err) {
|
||||
console.error("[useMcpRelayBridge] executeMcpTool error:", err);
|
||||
// Post a sanitized error result so the server-side blpop resolves.
|
||||
if (active.current) {
|
||||
await postResult(inv.requestId, sessionId, {
|
||||
error: `Plugin tool execution failed: ${err instanceof Error ? err.message : "unknown error"}`,
|
||||
}, active);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// POST result to /api/mcp/results
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
async function postResult(
|
||||
requestId: string,
|
||||
sessionId: string,
|
||||
result: unknown,
|
||||
active: { current: boolean },
|
||||
): Promise<void> {
|
||||
if (!active.current) return;
|
||||
|
||||
try {
|
||||
await fetch("/api/mcp/results", {
|
||||
method: "POST",
|
||||
headers: { "Content-Type": "application/json" },
|
||||
body: JSON.stringify({ requestId, sessionId, result }),
|
||||
});
|
||||
} catch (err) {
|
||||
console.error("[useMcpRelayBridge] postResult failed:", err);
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Type guard
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
function isToolInvocation(value: unknown): value is ToolInvocation {
|
||||
if (!value || typeof value !== "object") return false;
|
||||
const v = value as Record<string, unknown>;
|
||||
return (
|
||||
typeof v.requestId === "string" &&
|
||||
typeof v.tool === "string" &&
|
||||
typeof v.args === "object" &&
|
||||
v.args !== null
|
||||
);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Hook
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Polls /api/mcp/invocations and dispatches each pending tool invocation
|
||||
* to the owning plugin via plugin.executeMcpTool, then POSTs the result
|
||||
* back to /api/mcp/results so the server-side wait resolves.
|
||||
*
|
||||
* @param sessionId - Tab-scoped UUID from useSessionId. Pass empty to suppress polling.
|
||||
*/
|
||||
export function useMcpRelayBridge(sessionId: string): void {
|
||||
const activeRef = useRef(false);
|
||||
const inFlightRef = useRef(false);
|
||||
|
||||
useEffect(() => {
|
||||
if (!sessionId) return;
|
||||
|
||||
activeRef.current = true;
|
||||
|
||||
// Poll immediately on mount so the first invocation is dispatched
|
||||
// without waiting up to POLL_INTERVAL_MS. Mirrors useMcpCatalogPublisher.
|
||||
inFlightRef.current = true;
|
||||
void pollOnce(sessionId, activeRef).finally(() => {
|
||||
inFlightRef.current = false;
|
||||
});
|
||||
|
||||
const intervalId = setInterval(() => {
|
||||
if (inFlightRef.current) return;
|
||||
inFlightRef.current = true;
|
||||
void pollOnce(sessionId, activeRef).finally(() => {
|
||||
inFlightRef.current = false;
|
||||
});
|
||||
}, POLL_INTERVAL_MS);
|
||||
|
||||
return () => {
|
||||
activeRef.current = false;
|
||||
clearInterval(intervalId);
|
||||
};
|
||||
}, [sessionId]);
|
||||
}
|
||||
@@ -0,0 +1,57 @@
|
||||
import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
|
||||
import { renderHook, act } from "@testing-library/react";
|
||||
import { useSessionId } from "./useSessionId";
|
||||
|
||||
const SESSION_ID_KEY = "wwv-globe-session-id";
|
||||
|
||||
describe("useSessionId", () => {
|
||||
beforeEach(() => {
|
||||
sessionStorage.clear();
|
||||
vi.spyOn(crypto, "randomUUID");
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
vi.restoreAllMocks();
|
||||
});
|
||||
|
||||
it("returns a non-empty string after mount", async () => {
|
||||
const { result } = renderHook(() => useSessionId());
|
||||
|
||||
// After render + effect flush: returns a stable UUID
|
||||
await act(async () => {});
|
||||
expect(result.current).not.toBe("");
|
||||
expect(typeof result.current).toBe("string");
|
||||
});
|
||||
|
||||
it("generates a UUID and writes it to sessionStorage when none exists", async () => {
|
||||
expect(sessionStorage.getItem(SESSION_ID_KEY)).toBeNull();
|
||||
|
||||
const { result } = renderHook(() => useSessionId());
|
||||
await act(async () => {});
|
||||
|
||||
expect(crypto.randomUUID).toHaveBeenCalledOnce();
|
||||
const stored = sessionStorage.getItem(SESSION_ID_KEY);
|
||||
expect(stored).not.toBeNull();
|
||||
expect(result.current).toBe(stored);
|
||||
});
|
||||
|
||||
it("reuses the existing sessionStorage value without calling randomUUID", async () => {
|
||||
const existingId = "existing-session-id-abc";
|
||||
sessionStorage.setItem(SESSION_ID_KEY, existingId);
|
||||
|
||||
const { result } = renderHook(() => useSessionId());
|
||||
await act(async () => {});
|
||||
|
||||
expect(crypto.randomUUID).not.toHaveBeenCalled();
|
||||
expect(result.current).toBe(existingId);
|
||||
});
|
||||
|
||||
it("returns the same id on a second render (stable across rerenders)", async () => {
|
||||
const { result, rerender } = renderHook(() => useSessionId());
|
||||
await act(async () => {});
|
||||
|
||||
const firstId = result.current;
|
||||
rerender();
|
||||
expect(result.current).toBe(firstId);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,26 @@
|
||||
import { useRef, useState, useEffect } from "react";
|
||||
|
||||
const SESSION_ID_KEY = "wwv-globe-session-id";
|
||||
|
||||
export function useSessionId(): string {
|
||||
// resolvedRef caches the id after the first effect run so rerenders are free
|
||||
const resolvedRef = useRef<string>("");
|
||||
const [sessionId, setSessionId] = useState<string>("");
|
||||
|
||||
useEffect(() => {
|
||||
if (resolvedRef.current) return;
|
||||
|
||||
// sessionStorage is only available in the browser (this effect never runs on the server)
|
||||
const existing = sessionStorage.getItem(SESSION_ID_KEY);
|
||||
const id = existing ?? (() => {
|
||||
const newId = crypto.randomUUID();
|
||||
sessionStorage.setItem(SESSION_ID_KEY, newId);
|
||||
return newId;
|
||||
})();
|
||||
|
||||
resolvedRef.current = id;
|
||||
setSessionId(id);
|
||||
}, []);
|
||||
|
||||
return sessionId;
|
||||
}
|
||||
@@ -0,0 +1,266 @@
|
||||
/**
|
||||
* RED test scaffold for GlobeCommand type guard (Phase 19a Wave 0).
|
||||
*
|
||||
* These tests INTENTIONALLY FAIL because GlobeCommand.ts does not exist yet.
|
||||
* They lock the following contracts:
|
||||
*
|
||||
* CMD-01 valid pan command passes the guard
|
||||
* CMD-02 pan with non-number lat fails the guard
|
||||
* CMD-03 valid toggleLayer passes the guard
|
||||
* CMD-04 toggleLayer without layerId fails the guard
|
||||
* CMD-05 valid focusEntity passes the guard
|
||||
* CMD-06 valid setTimeline passes the guard
|
||||
* CMD-07 unknown type fails the guard
|
||||
* CMD-08 null/undefined/string all fail (never throws)
|
||||
*/
|
||||
|
||||
import { describe, it, expect } from "vitest";
|
||||
import { isValidGlobeCommand } from "./GlobeCommand";
|
||||
|
||||
describe("isValidGlobeCommand", () => {
|
||||
// CMD-01
|
||||
it("returns true for a valid pan command with required fields", () => {
|
||||
expect(
|
||||
isValidGlobeCommand({ type: "pan", lat: 1, lon: 2, alt: 3 })
|
||||
).toBe(true);
|
||||
});
|
||||
|
||||
// CMD-01 variant with optional fields
|
||||
it("returns true for pan with all optional fields", () => {
|
||||
expect(
|
||||
isValidGlobeCommand({
|
||||
type: "pan",
|
||||
lat: 40.7,
|
||||
lon: -74.0,
|
||||
alt: 500000,
|
||||
duration: 2,
|
||||
heading: 45,
|
||||
pitch: -30,
|
||||
})
|
||||
).toBe(true);
|
||||
});
|
||||
|
||||
// CMD-02
|
||||
it("returns false for pan when lat is not a number", () => {
|
||||
expect(
|
||||
isValidGlobeCommand({ type: "pan", lat: "north", lon: 2, alt: 3 })
|
||||
).toBe(false);
|
||||
});
|
||||
|
||||
it("returns false for pan when lon is not a number", () => {
|
||||
expect(
|
||||
isValidGlobeCommand({ type: "pan", lat: 1, lon: null, alt: 3 })
|
||||
).toBe(false);
|
||||
});
|
||||
|
||||
it("returns false for pan when alt is missing", () => {
|
||||
expect(
|
||||
isValidGlobeCommand({ type: "pan", lat: 1, lon: 2 })
|
||||
).toBe(false);
|
||||
});
|
||||
|
||||
// CMD-03
|
||||
it("returns true for a valid toggleLayer command", () => {
|
||||
expect(
|
||||
isValidGlobeCommand({ type: "toggleLayer", layerId: "ais" })
|
||||
).toBe(true);
|
||||
});
|
||||
|
||||
it("returns true for toggleLayer with enabled field", () => {
|
||||
expect(
|
||||
isValidGlobeCommand({ type: "toggleLayer", layerId: "aviation", enabled: false })
|
||||
).toBe(true);
|
||||
});
|
||||
|
||||
// CMD-04
|
||||
it("returns false for toggleLayer without layerId", () => {
|
||||
expect(
|
||||
isValidGlobeCommand({ type: "toggleLayer" })
|
||||
).toBe(false);
|
||||
});
|
||||
|
||||
it("returns false for toggleLayer with non-string layerId", () => {
|
||||
expect(
|
||||
isValidGlobeCommand({ type: "toggleLayer", layerId: 42 })
|
||||
).toBe(false);
|
||||
});
|
||||
|
||||
// CMD-05
|
||||
it("returns true for a valid focusEntity command with entityId", () => {
|
||||
expect(
|
||||
isValidGlobeCommand({ type: "focusEntity", entityId: "ship:1" })
|
||||
).toBe(true);
|
||||
});
|
||||
|
||||
it("returns true for focusEntity with lat/lon", () => {
|
||||
expect(
|
||||
isValidGlobeCommand({ type: "focusEntity", lat: 51.5, lon: -0.12 })
|
||||
).toBe(true);
|
||||
});
|
||||
|
||||
it("returns true for focusEntity with no fields (all optional)", () => {
|
||||
expect(
|
||||
isValidGlobeCommand({ type: "focusEntity" })
|
||||
).toBe(true);
|
||||
});
|
||||
|
||||
// CMD-06
|
||||
it("returns true for a valid setTimeline command with timeWindow", () => {
|
||||
expect(
|
||||
isValidGlobeCommand({ type: "setTimeline", timeWindow: "24h" })
|
||||
).toBe(true);
|
||||
});
|
||||
|
||||
it("returns true for setTimeline with all optional fields", () => {
|
||||
expect(
|
||||
isValidGlobeCommand({
|
||||
type: "setTimeline",
|
||||
currentTime: "2026-01-01T00:00:00.000Z",
|
||||
timeWindow: "6h",
|
||||
isPlaybackMode: true,
|
||||
})
|
||||
).toBe(true);
|
||||
});
|
||||
|
||||
it("returns true for setTimeline with no fields (all optional)", () => {
|
||||
expect(
|
||||
isValidGlobeCommand({ type: "setTimeline" })
|
||||
).toBe(true);
|
||||
});
|
||||
|
||||
// CMD-07
|
||||
it("returns false for an unknown type", () => {
|
||||
expect(
|
||||
isValidGlobeCommand({ type: "flyTo", lat: 1, lon: 2 })
|
||||
).toBe(false);
|
||||
});
|
||||
|
||||
it("returns false for an object with no type", () => {
|
||||
expect(
|
||||
isValidGlobeCommand({ lat: 1, lon: 2 })
|
||||
).toBe(false);
|
||||
});
|
||||
|
||||
// CMD-08
|
||||
it("returns false for null without throwing", () => {
|
||||
expect(isValidGlobeCommand(null)).toBe(false);
|
||||
});
|
||||
|
||||
it("returns false for undefined without throwing", () => {
|
||||
expect(isValidGlobeCommand(undefined)).toBe(false);
|
||||
});
|
||||
|
||||
it("returns false for a plain string without throwing", () => {
|
||||
expect(isValidGlobeCommand("pan")).toBe(false);
|
||||
});
|
||||
|
||||
it("returns false for a number without throwing", () => {
|
||||
expect(isValidGlobeCommand(42)).toBe(false);
|
||||
});
|
||||
|
||||
it("returns false for an array without throwing", () => {
|
||||
expect(isValidGlobeCommand([])).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("flyTo validator", () => {
|
||||
it("accepts valid point command with lat and lng only", () => {
|
||||
expect(isValidGlobeCommand({ type: "flyTo", lat: 51.5, lng: -0.1 })).toBe(true);
|
||||
});
|
||||
|
||||
it("accepts valid point command with lat, lng, and alt", () => {
|
||||
expect(isValidGlobeCommand({ type: "flyTo", lat: 51.5, lng: -0.1, alt: 15000 })).toBe(true);
|
||||
});
|
||||
|
||||
it("accepts valid command with a 4-element bbox [west,south,east,north]", () => {
|
||||
expect(isValidGlobeCommand({ type: "flyTo", lat: 51.5, lng: -0.1, bbox: [-1, 50, 1, 52] })).toBe(true);
|
||||
});
|
||||
|
||||
it("rejects bbox with wrong length (3 elements)", () => {
|
||||
expect(isValidGlobeCommand({ type: "flyTo", lat: 51.5, lng: -0.1, bbox: [-1, 50, 1] })).toBe(false);
|
||||
});
|
||||
|
||||
it("rejects lat out of range (>90)", () => {
|
||||
expect(isValidGlobeCommand({ type: "flyTo", lat: 91, lng: 0 })).toBe(false);
|
||||
});
|
||||
|
||||
it("rejects lng out of range (>180)", () => {
|
||||
expect(isValidGlobeCommand({ type: "flyTo", lat: 0, lng: 181 })).toBe(false);
|
||||
});
|
||||
|
||||
it("rejects negative alt (alt must be > 0 if provided)", () => {
|
||||
expect(isValidGlobeCommand({ type: "flyTo", lat: 0, lng: 0, alt: -1 })).toBe(false);
|
||||
});
|
||||
|
||||
it("rejects bbox with non-numeric element", () => {
|
||||
expect(isValidGlobeCommand({ type: "flyTo", lat: 0, lng: 0, bbox: ["west", 50, 1, 52] })).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("setFilter / clearFilter validator", () => {
|
||||
it("accepts setFilter with a select filter value", () => {
|
||||
expect(
|
||||
isValidGlobeCommand({ type: "setFilter", pluginId: "flights", filters: { status: { type: "select", values: ["airborne"] } } })
|
||||
).toBe(true);
|
||||
});
|
||||
|
||||
it("accepts setFilter with a range filter value", () => {
|
||||
expect(
|
||||
isValidGlobeCommand({ type: "setFilter", pluginId: "flights", filters: { alt: { type: "range", min: 0, max: 1000 } } })
|
||||
).toBe(true);
|
||||
});
|
||||
|
||||
it("accepts setFilter with a boolean filter value", () => {
|
||||
expect(
|
||||
isValidGlobeCommand({ type: "setFilter", pluginId: "flights", filters: { live: { type: "boolean", value: true } } })
|
||||
).toBe(true);
|
||||
});
|
||||
|
||||
it("accepts setFilter with a text filter value", () => {
|
||||
expect(
|
||||
isValidGlobeCommand({ type: "setFilter", pluginId: "flights", filters: { name: { type: "text", value: "ba" } } })
|
||||
).toBe(true);
|
||||
});
|
||||
|
||||
it("rejects setFilter with an empty pluginId", () => {
|
||||
expect(
|
||||
isValidGlobeCommand({ type: "setFilter", pluginId: "", filters: {} })
|
||||
).toBe(false);
|
||||
});
|
||||
|
||||
it("rejects setFilter when select values is not an array", () => {
|
||||
expect(
|
||||
isValidGlobeCommand({ type: "setFilter", pluginId: "flights", filters: { x: { type: "select", values: "nope" } } })
|
||||
).toBe(false);
|
||||
});
|
||||
|
||||
it("rejects setFilter when range min is not a number", () => {
|
||||
expect(
|
||||
isValidGlobeCommand({ type: "setFilter", pluginId: "flights", filters: { x: { type: "range", min: "0", max: 1 } } })
|
||||
).toBe(false);
|
||||
});
|
||||
|
||||
it("rejects setFilter with an unknown filter type", () => {
|
||||
expect(
|
||||
isValidGlobeCommand({ type: "setFilter", pluginId: "flights", filters: { x: { type: "bogus" } } })
|
||||
).toBe(false);
|
||||
});
|
||||
|
||||
it("rejects setFilter when filters is not an object", () => {
|
||||
expect(
|
||||
isValidGlobeCommand({ type: "setFilter", pluginId: "flights", filters: null })
|
||||
).toBe(false);
|
||||
});
|
||||
|
||||
it("accepts clearFilter with no pluginId (clear all)", () => {
|
||||
expect(isValidGlobeCommand({ type: "clearFilter" })).toBe(true);
|
||||
});
|
||||
|
||||
it("accepts clearFilter with a pluginId", () => {
|
||||
expect(isValidGlobeCommand({ type: "clearFilter", pluginId: "flights" })).toBe(true);
|
||||
});
|
||||
|
||||
it("rejects clearFilter when pluginId is not a string", () => {
|
||||
expect(isValidGlobeCommand({ type: "clearFilter", pluginId: 123 })).toBe(false);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,151 @@
|
||||
import type { FilterValue } from "@/core/plugins/PluginTypes";
|
||||
|
||||
// Must stay in sync with the TimeWindow union in @worldwideview/wwv-plugin-sdk.
|
||||
export const TIME_WINDOW_VALUES = ["1h", "6h", "24h", "48h", "7d"] as const;
|
||||
export type TimeWindowLiteral = (typeof TIME_WINDOW_VALUES)[number];
|
||||
|
||||
export type GlobeCommand =
|
||||
| { type: "pan"; lat: number; lon: number; alt: number; duration?: number; heading?: number; pitch?: number }
|
||||
| { type: "focusEntity"; entityId?: string; lat?: number; lon?: number }
|
||||
| { type: "toggleLayer"; layerId: string; enabled?: boolean }
|
||||
| { type: "setTimeline"; currentTime?: string; timeWindow?: TimeWindowLiteral; isPlaybackMode?: boolean }
|
||||
| { type: "flyTo"; lat: number; lng: number; alt?: number; bbox?: [number, number, number, number] }
|
||||
| { type: "setFilter"; pluginId: string; filters: Record<string, FilterValue> }
|
||||
| { type: "clearFilter"; pluginId?: string };
|
||||
|
||||
function isNumber(v: unknown): v is number {
|
||||
return typeof v === "number" && isFinite(v);
|
||||
}
|
||||
|
||||
function isValidLat(v: unknown): v is number {
|
||||
return isNumber(v) && v >= -90 && v <= 90;
|
||||
}
|
||||
|
||||
function isValidLon(v: unknown): v is number {
|
||||
return isNumber(v) && v >= -180 && v <= 180;
|
||||
}
|
||||
|
||||
function isValidAlt(v: unknown): v is number {
|
||||
return isNumber(v) && v > 0;
|
||||
}
|
||||
|
||||
function isString(v: unknown): v is string {
|
||||
return typeof v === "string";
|
||||
}
|
||||
|
||||
function isOptionalNumber(v: unknown): boolean {
|
||||
return v === undefined || isNumber(v);
|
||||
}
|
||||
|
||||
function isOptionalString(v: unknown): boolean {
|
||||
return v === undefined || isString(v);
|
||||
}
|
||||
|
||||
function isOptionalBoolean(v: unknown): boolean {
|
||||
return v === undefined || typeof v === "boolean";
|
||||
}
|
||||
|
||||
const TIME_WINDOW_SET = new Set<string>(TIME_WINDOW_VALUES);
|
||||
|
||||
function isValidTimeWindow(v: unknown): v is TimeWindowLiteral {
|
||||
return typeof v === "string" && TIME_WINDOW_SET.has(v);
|
||||
}
|
||||
|
||||
function isOptionalTimeWindow(v: unknown): boolean {
|
||||
return v === undefined || isValidTimeWindow(v);
|
||||
}
|
||||
|
||||
function isValidDateString(v: unknown): boolean {
|
||||
return typeof v === "string" && !Number.isNaN(Date.parse(v));
|
||||
}
|
||||
|
||||
function isOptionalDateString(v: unknown): boolean {
|
||||
return v === undefined || isValidDateString(v);
|
||||
}
|
||||
|
||||
function isValidFilterValue(v: unknown): v is FilterValue {
|
||||
if (v === null || typeof v !== "object" || Array.isArray(v)) return false;
|
||||
const fv = v as Record<string, unknown>;
|
||||
switch (fv["type"]) {
|
||||
case "text":
|
||||
return typeof fv["value"] === "string";
|
||||
case "select":
|
||||
return Array.isArray(fv["values"]) && fv["values"].every((x) => typeof x === "string");
|
||||
case "range":
|
||||
return isNumber(fv["min"]) && isNumber(fv["max"]);
|
||||
case "boolean":
|
||||
return typeof fv["value"] === "boolean";
|
||||
default:
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
export function isValidGlobeCommand(obj: unknown): obj is GlobeCommand {
|
||||
if (obj === null || typeof obj !== "object" || Array.isArray(obj)) {
|
||||
return false;
|
||||
}
|
||||
|
||||
const cmd = obj as Record<string, unknown>;
|
||||
|
||||
switch (cmd["type"]) {
|
||||
case "pan":
|
||||
return (
|
||||
isValidLat(cmd["lat"]) &&
|
||||
isValidLon(cmd["lon"]) &&
|
||||
isValidAlt(cmd["alt"]) &&
|
||||
isOptionalNumber(cmd["duration"]) &&
|
||||
isOptionalNumber(cmd["heading"]) &&
|
||||
isOptionalNumber(cmd["pitch"])
|
||||
);
|
||||
|
||||
case "focusEntity":
|
||||
return (
|
||||
isOptionalString(cmd["entityId"]) &&
|
||||
(cmd["lat"] === undefined || isValidLat(cmd["lat"])) &&
|
||||
(cmd["lon"] === undefined || isValidLon(cmd["lon"]))
|
||||
);
|
||||
|
||||
case "toggleLayer":
|
||||
return (
|
||||
isString(cmd["layerId"]) &&
|
||||
isOptionalBoolean(cmd["enabled"])
|
||||
);
|
||||
|
||||
case "setTimeline":
|
||||
return (
|
||||
isOptionalDateString(cmd["currentTime"]) &&
|
||||
isOptionalTimeWindow(cmd["timeWindow"]) &&
|
||||
isOptionalBoolean(cmd["isPlaybackMode"])
|
||||
);
|
||||
|
||||
case "flyTo": {
|
||||
if (!isValidLat(cmd["lat"])) return false;
|
||||
if (!(isNumber(cmd["lng"]) && (cmd["lng"] as number) >= -180 && (cmd["lng"] as number) <= 180)) return false;
|
||||
if (!(isOptionalNumber(cmd["alt"]) && (cmd["alt"] === undefined || isValidAlt(cmd["alt"])))) return false;
|
||||
if (cmd["bbox"] !== undefined) {
|
||||
const bbox = cmd["bbox"];
|
||||
if (!Array.isArray(bbox) || bbox.length !== 4) return false;
|
||||
if (!bbox.every((v: unknown) => isNumber(v))) return false;
|
||||
const [west, south, east, north] = bbox as number[];
|
||||
if (west < -180 || west > 180) return false;
|
||||
if (south < -90 || south > 90) return false;
|
||||
if (east < -180 || east > 180) return false;
|
||||
if (north < -90 || north > 90) return false;
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
case "setFilter": {
|
||||
if (typeof cmd["pluginId"] !== "string" || cmd["pluginId"] === "") return false;
|
||||
const filters = cmd["filters"];
|
||||
if (filters === null || typeof filters !== "object" || Array.isArray(filters)) return false;
|
||||
return Object.values(filters as Record<string, unknown>).every(isValidFilterValue);
|
||||
}
|
||||
|
||||
case "clearFilter":
|
||||
return isOptionalString(cmd["pluginId"]);
|
||||
|
||||
default:
|
||||
return false;
|
||||
}
|
||||
}
|
||||
@@ -10,6 +10,7 @@ import {
|
||||
getApprovedUnverifiedIds,
|
||||
approveUnverifiedPlugin,
|
||||
} from "@/lib/marketplace/trustedPlugins";
|
||||
import { getDisabledPluginIds } from "@/core/plugins/pluginPreferences";
|
||||
import { isDemo } from "@/core/edition";
|
||||
|
||||
/**
|
||||
@@ -66,6 +67,7 @@ export function useMarketplaceSync(hostReady: boolean) {
|
||||
|
||||
async function loadManifest(manifest: PluginManifest) {
|
||||
if (!manifest.id || loadedIds.current.has(manifest.id)) return;
|
||||
if (getDisabledPluginIds().has(manifest.id)) return;
|
||||
if (pluginManager.getPlugin(manifest.id)) {
|
||||
loadedIds.current.add(manifest.id);
|
||||
return;
|
||||
|
||||
@@ -13,4 +13,5 @@ export type {
|
||||
FieldMapping,
|
||||
RenderingConfig,
|
||||
PluginManifest,
|
||||
McpToolDeclaration,
|
||||
} from "@worldwideview/wwv-plugin-sdk";
|
||||
@@ -0,0 +1,25 @@
|
||||
const DISABLED_KEY = "wwv-disabled-plugins";
|
||||
|
||||
export function getDisabledPluginIds(): Set<string> {
|
||||
try {
|
||||
const raw = localStorage.getItem(DISABLED_KEY);
|
||||
if (!raw) return new Set();
|
||||
return new Set<string>(JSON.parse(raw));
|
||||
} catch {
|
||||
return new Set();
|
||||
}
|
||||
}
|
||||
|
||||
export function setPluginDisabled(pluginId: string, disabled: boolean): void {
|
||||
try {
|
||||
const ids = getDisabledPluginIds();
|
||||
if (disabled) {
|
||||
ids.add(pluginId);
|
||||
} else {
|
||||
ids.delete(pluginId);
|
||||
}
|
||||
localStorage.setItem(DISABLED_KEY, JSON.stringify([...ids]));
|
||||
} catch {
|
||||
// ignore storage errors
|
||||
}
|
||||
}
|
||||
@@ -1,59 +1,292 @@
|
||||
/* eslint-disable @typescript-eslint/no-explicit-any */
|
||||
/**
|
||||
* Tests for validateManifest (extended for Phase 21 Wave 0 RED).
|
||||
*
|
||||
* The existing test suite covers the base manifest shape. This extended file
|
||||
* adds RED assertions for the new Phase 21 fields that Wave 1 will add:
|
||||
*
|
||||
* MAN-01 mcpTools array: each entry must have name, description, inputSchema
|
||||
* MAN-02 mcpTools tool names: only [a-zA-Z0-9_-] are safe identifiers
|
||||
* MAN-03 mcpCapabilities must be string[] when present (non-array is rejected)
|
||||
* MAN-04 Absence of an "execution" field is fine (v3 -- no server-side execution)
|
||||
* MAN-05 A manifest with no mcpTools / mcpCapabilities still passes (optional fields)
|
||||
* MAN-06 mcpTools entries missing name are rejected
|
||||
* MAN-07 mcpTools entries missing description are rejected
|
||||
* MAN-08 mcpTools entries missing inputSchema are rejected
|
||||
*/
|
||||
|
||||
import { describe, it, expect } from "vitest";
|
||||
import { validateManifest } from "./validateManifest";
|
||||
import type { PluginManifest } from "./PluginManifest";
|
||||
|
||||
describe("validateManifest", () => {
|
||||
it("should validate a correct manifest", () => {
|
||||
const manifest: any = {
|
||||
id: "test-plugin",
|
||||
name: "Test Plugin",
|
||||
version: "1.0.0",
|
||||
type: "data-layer",
|
||||
trust: "verified",
|
||||
capabilities: ["streaming"],
|
||||
entry: "/plugins/test.js"
|
||||
};
|
||||
const result = validateManifest(manifest);
|
||||
expect(result.valid).toBe(true);
|
||||
expect(result.errors).toHaveLength(0);
|
||||
});
|
||||
// ---------------------------------------------------------------------------
|
||||
// Helpers
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
it("should flag missing required fields", () => {
|
||||
const result = validateManifest({});
|
||||
expect(result.valid).toBe(false);
|
||||
expect(result.errors).toContain("Missing required field: id");
|
||||
expect(result.errors).toContain("Missing required field: name");
|
||||
expect(result.errors).toContain("Missing required field: version");
|
||||
expect(result.errors).toContain("Missing required field: entry");
|
||||
});
|
||||
function baseManifest(overrides: Record<string, unknown> = {}): Partial<PluginManifest> {
|
||||
return {
|
||||
id: "test-plugin",
|
||||
name: "Test Plugin",
|
||||
version: "1.0.0",
|
||||
type: "data-layer",
|
||||
format: "bundle",
|
||||
trust: "built-in",
|
||||
capabilities: ["data:own"],
|
||||
entry: "/plugins/test/frontend.mjs",
|
||||
...overrides,
|
||||
} as Partial<PluginManifest>;
|
||||
}
|
||||
|
||||
it("should flag invalid entry URLs", () => {
|
||||
const manifest: any = {
|
||||
id: "p1",
|
||||
name: "n1",
|
||||
version: "1",
|
||||
type: "data-layer",
|
||||
trust: "verified",
|
||||
capabilities: ["c1"],
|
||||
entry: "https://hacker.com/malicious.js"
|
||||
};
|
||||
const result = validateManifest(manifest);
|
||||
expect(result.valid).toBe(false);
|
||||
expect(result.errors).toContain("entry URL must be a relative path, CDN, localhost, or worldwideview.dev domain");
|
||||
});
|
||||
// ---------------------------------------------------------------------------
|
||||
// Existing base tests (preserved, no `any`)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
it("should require extends for extensions", () => {
|
||||
const manifest: any = {
|
||||
id: "p1",
|
||||
name: "n1",
|
||||
version: "1",
|
||||
type: "extension",
|
||||
trust: "verified",
|
||||
capabilities: ["c1"],
|
||||
entry: "/p.js"
|
||||
};
|
||||
const result = validateManifest(manifest);
|
||||
expect(result.valid).toBe(false);
|
||||
expect(result.errors).toContain("Extension plugins require a non-empty extends array");
|
||||
});
|
||||
describe("validateManifest base contract", () => {
|
||||
it("accepts a correct manifest", () => {
|
||||
const result = validateManifest(baseManifest({ trust: "verified" }));
|
||||
expect(result.valid).toBe(true);
|
||||
expect(result.errors).toHaveLength(0);
|
||||
});
|
||||
|
||||
it("flags missing required fields", () => {
|
||||
const result = validateManifest({});
|
||||
expect(result.valid).toBe(false);
|
||||
expect(result.errors).toContain("Missing required field: id");
|
||||
expect(result.errors).toContain("Missing required field: name");
|
||||
expect(result.errors).toContain("Missing required field: version");
|
||||
expect(result.errors).toContain("Missing required field: entry");
|
||||
});
|
||||
|
||||
it("flags invalid entry URLs", () => {
|
||||
const result = validateManifest(baseManifest({ entry: "https://hacker.com/malicious.js" }));
|
||||
expect(result.valid).toBe(false);
|
||||
expect(result.errors).toContain(
|
||||
"entry URL must be a relative path, CDN, localhost, or worldwideview.dev domain",
|
||||
);
|
||||
});
|
||||
|
||||
it("requires extends for extension plugins", () => {
|
||||
const result = validateManifest(baseManifest({ type: "extension" }));
|
||||
expect(result.valid).toBe(false);
|
||||
expect(result.errors).toContain("Extension plugins require a non-empty extends array");
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// MAN-05: manifest without mcpTools / mcpCapabilities still passes
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("validateManifest optional mcp fields (MAN-05)", () => {
|
||||
it("accepts a manifest with no mcpTools or mcpCapabilities", () => {
|
||||
const result = validateManifest(baseManifest());
|
||||
expect(result.valid).toBe(true);
|
||||
expect(result.errors).toHaveLength(0);
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// MAN-01 / MAN-06 / MAN-07 / MAN-08: mcpTools entry structure
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("validateManifest mcpTools entry structure (MAN-01)", () => {
|
||||
it("accepts a manifest with a well-formed mcpTools array", () => {
|
||||
// v3: no execution field -- only name, description, inputSchema
|
||||
const manifest = baseManifest({
|
||||
mcpTools: [
|
||||
{
|
||||
name: "decode_squawk",
|
||||
description: "Decodes an aviation squawk code.",
|
||||
inputSchema: {
|
||||
type: "object",
|
||||
properties: { squawk: { type: "string" } },
|
||||
required: ["squawk"],
|
||||
},
|
||||
},
|
||||
],
|
||||
});
|
||||
|
||||
const result = validateManifest(manifest);
|
||||
// Wave 1 will validate mcpTools; current code ignores unknown fields (no false rejection).
|
||||
// No mcpTools-specific errors should be present when the entry is well-formed.
|
||||
const hasMcpToolsError = result.errors.some((e) => /mcpTools/i.test(e));
|
||||
expect(hasMcpToolsError).toBe(false);
|
||||
});
|
||||
|
||||
it("rejects mcpTools entries missing name (MAN-06)", () => {
|
||||
const manifest = baseManifest({
|
||||
mcpTools: [
|
||||
{
|
||||
// name absent
|
||||
description: "A tool with no name.",
|
||||
inputSchema: { type: "object" },
|
||||
},
|
||||
],
|
||||
});
|
||||
|
||||
// RED: Wave 1 adds the name-presence check.
|
||||
const result = validateManifest(manifest);
|
||||
const hasMcpNameError = result.errors.some(
|
||||
(e) => /mcpTools.*name/i.test(e) || /name.*mcpTools/i.test(e),
|
||||
);
|
||||
expect(hasMcpNameError).toBe(true);
|
||||
});
|
||||
|
||||
it("rejects mcpTools entries missing description (MAN-07)", () => {
|
||||
const manifest = baseManifest({
|
||||
mcpTools: [
|
||||
{
|
||||
name: "decode_squawk",
|
||||
// description absent
|
||||
inputSchema: { type: "object" },
|
||||
},
|
||||
],
|
||||
});
|
||||
|
||||
const result = validateManifest(manifest);
|
||||
// RED: Wave 1 adds the description-presence check.
|
||||
const hasMcpDescError = result.errors.some(
|
||||
(e) => /mcpTools.*description/i.test(e) || /description.*mcpTools/i.test(e),
|
||||
);
|
||||
expect(hasMcpDescError).toBe(true);
|
||||
});
|
||||
|
||||
it("rejects mcpTools entries missing inputSchema (MAN-08)", () => {
|
||||
const manifest = baseManifest({
|
||||
mcpTools: [
|
||||
{
|
||||
name: "decode_squawk",
|
||||
description: "Decodes a squawk code.",
|
||||
// inputSchema absent
|
||||
},
|
||||
],
|
||||
});
|
||||
|
||||
const result = validateManifest(manifest);
|
||||
// RED: Wave 1 adds the inputSchema-presence check.
|
||||
const hasMcpSchemaError = result.errors.some(
|
||||
(e) => /mcpTools.*inputSchema/i.test(e) || /inputSchema.*mcpTools/i.test(e),
|
||||
);
|
||||
expect(hasMcpSchemaError).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// MAN-02: tool name identifier safety
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("validateManifest mcpTools name safety (MAN-02)", () => {
|
||||
it("accepts tool names that are safe identifiers [a-zA-Z0-9_-]", () => {
|
||||
const manifest = baseManifest({
|
||||
mcpTools: [
|
||||
{
|
||||
name: "decode_squawk-v2",
|
||||
description: "Safe name.",
|
||||
inputSchema: { type: "object" },
|
||||
},
|
||||
],
|
||||
});
|
||||
|
||||
const result = validateManifest(manifest);
|
||||
// The name is safe; no name-safety error should appear (even in RED state).
|
||||
const hasNameSafetyError = result.errors.some((e) =>
|
||||
/unsafe|identifier|invalid.*name|name.*invalid/i.test(e),
|
||||
);
|
||||
expect(hasNameSafetyError).toBe(false);
|
||||
});
|
||||
|
||||
it("rejects tool names containing characters outside [a-zA-Z0-9_-]", () => {
|
||||
const manifest = baseManifest({
|
||||
mcpTools: [
|
||||
{
|
||||
name: "bad name!",
|
||||
description: "Unsafe name.",
|
||||
inputSchema: { type: "object" },
|
||||
},
|
||||
],
|
||||
});
|
||||
|
||||
const result = validateManifest(manifest);
|
||||
// RED: Wave 1 must add the safe-identifier check.
|
||||
const hasNameSafetyError = result.errors.some((e) =>
|
||||
/identifier|unsafe|invalid.*name|name.*invalid/i.test(e),
|
||||
);
|
||||
expect(hasNameSafetyError).toBe(true);
|
||||
});
|
||||
|
||||
it("rejects tool names with spaces", () => {
|
||||
const manifest = baseManifest({
|
||||
mcpTools: [
|
||||
{
|
||||
name: "has space",
|
||||
description: "Space in name.",
|
||||
inputSchema: { type: "object" },
|
||||
},
|
||||
],
|
||||
});
|
||||
|
||||
const result = validateManifest(manifest);
|
||||
const hasNameSafetyError = result.errors.some((e) =>
|
||||
/identifier|unsafe|invalid.*name|name.*invalid/i.test(e),
|
||||
);
|
||||
expect(hasNameSafetyError).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// MAN-03: mcpCapabilities must be string[] when present
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("validateManifest mcpCapabilities field (MAN-03)", () => {
|
||||
it("accepts a manifest with a valid mcpCapabilities string array", () => {
|
||||
const manifest = baseManifest({ mcpCapabilities: ["point-layer"] });
|
||||
|
||||
const result = validateManifest(manifest);
|
||||
// Wave 1 adds the check; current code ignores the field -- no false rejection.
|
||||
const hasMcpCapError = result.errors.some((e) => /mcpCapabilities/i.test(e));
|
||||
expect(hasMcpCapError).toBe(false);
|
||||
});
|
||||
|
||||
it("rejects a non-array mcpCapabilities (string instead of array)", () => {
|
||||
const manifest = baseManifest({ mcpCapabilities: "point-layer" });
|
||||
|
||||
const result = validateManifest(manifest);
|
||||
// RED: Wave 1 must add this check.
|
||||
const hasMcpCapError = result.errors.some((e) => /mcpCapabilities/i.test(e));
|
||||
expect(hasMcpCapError).toBe(true);
|
||||
});
|
||||
|
||||
it("rejects mcpCapabilities containing non-string entries", () => {
|
||||
const manifest = baseManifest({ mcpCapabilities: ["point-layer", 42] });
|
||||
|
||||
const result = validateManifest(manifest);
|
||||
// RED: Wave 1 must add this check.
|
||||
const hasMcpCapError = result.errors.some((e) => /mcpCapabilities/i.test(e));
|
||||
expect(hasMcpCapError).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// MAN-04: no "execution" field required (v3 -- server never executes plugin tools)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("validateManifest no execution field required (MAN-04)", () => {
|
||||
it("accepts a manifest whose mcpTools entry has no execution field", () => {
|
||||
const manifest = baseManifest({
|
||||
mcpTools: [
|
||||
{
|
||||
name: "decode_squawk",
|
||||
description: "Decodes a squawk code.",
|
||||
inputSchema: {
|
||||
type: "object",
|
||||
properties: { squawk: { type: "string" } },
|
||||
},
|
||||
// NO execution field -- v3 does not use server-side execution
|
||||
},
|
||||
],
|
||||
});
|
||||
|
||||
const result = validateManifest(manifest);
|
||||
// Absence of execution must NOT produce an error of any kind.
|
||||
const hasExecutionError = result.errors.some((e) => /execution/i.test(e));
|
||||
expect(hasExecutionError).toBe(false);
|
||||
});
|
||||
});
|
||||
@@ -19,6 +19,9 @@ export interface ValidationResult {
|
||||
const VALID_TYPES = ["data-layer", "extension"] as const;
|
||||
const VALID_TRUSTS = ["built-in", "verified", "unverified"] as const;
|
||||
|
||||
/** Regex for a safe MCP tool name identifier: only [a-zA-Z0-9_-]. */
|
||||
const SAFE_TOOL_NAME = /^[a-zA-Z0-9_-]+$/;
|
||||
|
||||
/**
|
||||
* Validates a plugin manifest for structural integrity and security compliance.
|
||||
* This is the primary security gate for the WorldWideView plugin ecosystem.
|
||||
@@ -76,5 +79,52 @@ export function validateManifest(
|
||||
}
|
||||
}
|
||||
|
||||
// MAN-03: mcpCapabilities must be string[] when present
|
||||
if ("mcpCapabilities" in manifest && manifest.mcpCapabilities !== undefined) {
|
||||
if (!Array.isArray(manifest.mcpCapabilities)) {
|
||||
errors.push("mcpCapabilities must be a string array when present");
|
||||
} else {
|
||||
const allStrings = (manifest.mcpCapabilities as unknown[]).every(
|
||||
(c) => typeof c === "string",
|
||||
);
|
||||
if (!allStrings) {
|
||||
errors.push("mcpCapabilities must contain only strings");
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// MAN-01 / MAN-02 / MAN-06 / MAN-07 / MAN-08: validate mcpTools entries
|
||||
if ("mcpTools" in manifest && manifest.mcpTools !== undefined) {
|
||||
if (!Array.isArray(manifest.mcpTools)) {
|
||||
errors.push("mcpTools must be an array when present");
|
||||
} else {
|
||||
(manifest.mcpTools as unknown as Record<string, unknown>[]).forEach((tool, idx) => {
|
||||
const prefix = `mcpTools[${idx}]`;
|
||||
|
||||
// MAN-06: name must be present
|
||||
if (typeof tool.name !== "string" || !(tool.name as string).trim()) {
|
||||
errors.push(`${prefix}: mcpTools entry missing required field: name`);
|
||||
} else {
|
||||
// MAN-02: name must be a safe identifier
|
||||
if (!SAFE_TOOL_NAME.test(tool.name as string)) {
|
||||
errors.push(
|
||||
`${prefix}: mcpTools tool name "${tool.name}" contains invalid identifier characters; only [a-zA-Z0-9_-] are allowed`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
// MAN-07: description must be present
|
||||
if (typeof tool.description !== "string" || !(tool.description as string).trim()) {
|
||||
errors.push(`${prefix}: mcpTools entry missing required field: description`);
|
||||
}
|
||||
|
||||
// MAN-08: inputSchema must be present and be an object
|
||||
if (tool.inputSchema === undefined || tool.inputSchema === null || typeof tool.inputSchema !== "object") {
|
||||
errors.push(`${prefix}: mcpTools entry missing required field: inputSchema`);
|
||||
}
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
return { valid: errors.length === 0, errors };
|
||||
}
|
||||
@@ -0,0 +1,19 @@
|
||||
import { vi } from "vitest";
|
||||
|
||||
/**
|
||||
* Manual mock for `@/lib/prisma`.
|
||||
*
|
||||
* The real module re-exports a Prisma client whose underlying singleton
|
||||
* (`@/lib/db`) throws on any property access when DATABASE_URL is unset (the
|
||||
* test environment). That makes vitest's automock unusable here, so this manual
|
||||
* mock supplies a deep-mocked `prisma.favorite` surface that tests can drive
|
||||
* via `vi.mocked(prisma, true)`.
|
||||
*/
|
||||
export const prisma = {
|
||||
favorite: {
|
||||
upsert: vi.fn(),
|
||||
findMany: vi.fn(),
|
||||
delete: vi.fn(),
|
||||
deleteMany: vi.fn(),
|
||||
},
|
||||
};
|
||||
@@ -0,0 +1,178 @@
|
||||
import {
|
||||
describe, it, expect, vi, beforeEach
|
||||
} from "vitest";
|
||||
import { createHmac } from "crypto";
|
||||
import { generateApiKey, authenticateApiKey } from "./apiKeyAuth";
|
||||
import { prisma } from "@/lib/db";
|
||||
|
||||
vi.mock("@/lib/db", () => ({
|
||||
prisma: {
|
||||
userApiKey: {
|
||||
findUnique: vi.fn(),
|
||||
create: vi.fn(),
|
||||
findMany: vi.fn(),
|
||||
count: vi.fn(),
|
||||
deleteMany: vi.fn(),
|
||||
update: vi.fn(),
|
||||
},
|
||||
},
|
||||
}));
|
||||
|
||||
vi.mock("@/core/edition", () => ({
|
||||
isDemo: false,
|
||||
}));
|
||||
|
||||
// AUTH_SECRET must be set so getSigningKey() does not throw in the test env
|
||||
process.env.AUTH_SECRET = "test-signing-key-for-unit-tests";
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// generateApiKey — KEY-01
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("generateApiKey", () => {
|
||||
it("returns an object with prefix, secret, hashedSecret, fullToken", () => {
|
||||
const key = generateApiKey();
|
||||
expect(key).toHaveProperty("prefix");
|
||||
expect(key).toHaveProperty("secret");
|
||||
expect(key).toHaveProperty("hashedSecret");
|
||||
expect(key).toHaveProperty("fullToken");
|
||||
});
|
||||
|
||||
it("prefix starts with 'wwv_'", () => {
|
||||
const key = generateApiKey();
|
||||
expect(key.prefix).toMatch(/^wwv_/);
|
||||
});
|
||||
|
||||
it("fullToken equals prefix.secret", () => {
|
||||
const key = generateApiKey();
|
||||
expect(key.fullToken).toBe(`${key.prefix}.${key.secret}`);
|
||||
});
|
||||
|
||||
it("secret is not equal to hashedSecret (secret is plaintext, hashedSecret is HMAC hex)", () => {
|
||||
const key = generateApiKey();
|
||||
expect(key.secret).not.toBe(key.hashedSecret);
|
||||
});
|
||||
|
||||
it("hashedSecret is a valid 64-char hex string (SHA-256 output)", () => {
|
||||
const key = generateApiKey();
|
||||
expect(key.hashedSecret).toMatch(/^[0-9a-f]{64}$/);
|
||||
});
|
||||
|
||||
it("two calls produce different prefixes (random)", () => {
|
||||
const a = generateApiKey();
|
||||
const b = generateApiKey();
|
||||
expect(a.prefix).not.toBe(b.prefix);
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// authenticateApiKey — KEY-02, API-01
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("authenticateApiKey", () => {
|
||||
beforeEach(() => {
|
||||
vi.resetAllMocks();
|
||||
});
|
||||
|
||||
it("returns null when Authorization header is missing", async () => {
|
||||
const req = new Request("http://localhost/api/test");
|
||||
const result = await authenticateApiKey(req);
|
||||
expect(result).toBeNull();
|
||||
});
|
||||
|
||||
it("returns null when Authorization header is not Bearer", async () => {
|
||||
const req = new Request("http://localhost/api/test", {
|
||||
headers: { authorization: "Basic abc123" },
|
||||
});
|
||||
const result = await authenticateApiKey(req);
|
||||
expect(result).toBeNull();
|
||||
});
|
||||
|
||||
it("returns null when token has no '.' separator", async () => {
|
||||
const req = new Request("http://localhost/api/test", {
|
||||
headers: { authorization: "Bearer wwv_XXXXXXXX" },
|
||||
});
|
||||
const result = await authenticateApiKey(req);
|
||||
expect(result).toBeNull();
|
||||
});
|
||||
|
||||
it("returns null on unknown prefix (findUnique -> null) and does NOT throw", async () => {
|
||||
vi.mocked(prisma.userApiKey.findUnique).mockResolvedValue(null);
|
||||
const req = new Request("http://localhost/api/test", {
|
||||
headers: { authorization: "Bearer wwv_XXXXXXXX.fakesecret" },
|
||||
});
|
||||
await expect(authenticateApiKey(req)).resolves.toBeNull();
|
||||
});
|
||||
|
||||
it("returns null on valid prefix but wrong secret (HMAC mismatch)", async () => {
|
||||
// Store a HMAC of a different secret so comparison always fails
|
||||
const wrongHash = createHmac("sha256", "test-signing-key-for-unit-tests")
|
||||
.update("correct-secret")
|
||||
.digest("hex");
|
||||
|
||||
vi.mocked(prisma.userApiKey.findUnique).mockResolvedValue({
|
||||
id: "key-id-1",
|
||||
userId: "user-123",
|
||||
hashedSecret: wrongHash,
|
||||
} as never);
|
||||
const req = new Request("http://localhost/api/test", {
|
||||
headers: { authorization: "Bearer wwv_XXXXXXXX.wrongsecret" },
|
||||
});
|
||||
const result = await authenticateApiKey(req);
|
||||
expect(result).toBeNull();
|
||||
});
|
||||
|
||||
it("returns { userId, keyId } on valid token (API-01)", async () => {
|
||||
// Generate a real key so we have a matching prefix + secret pair
|
||||
const { prefix, secret, hashedSecret } = generateApiKey();
|
||||
vi.mocked(prisma.userApiKey.findUnique).mockResolvedValue({
|
||||
id: "key-id-real",
|
||||
userId: "user-real",
|
||||
hashedSecret,
|
||||
} as never);
|
||||
vi.mocked(prisma.userApiKey.update).mockResolvedValue({} as never);
|
||||
|
||||
const req = new Request("http://localhost/api/test", {
|
||||
headers: { authorization: `Bearer ${prefix}.${secret}` },
|
||||
});
|
||||
const result = await authenticateApiKey(req);
|
||||
expect(result).toEqual({ userId: "user-real", keyId: "key-id-real" });
|
||||
});
|
||||
|
||||
// Security contract: miss path runs timingSafeEqual against a dummy digest —
|
||||
// both buffers are the same length, so the compare is constant-work regardless
|
||||
// of whether the prefix was found. HMAC is microsecond-fast; we assert the
|
||||
// CONTRACT (no timing oracle) by confirming the function still returns null,
|
||||
// not by measuring elapsed time (HMAC has no measurable delay to assert on).
|
||||
it("miss path completes and returns null — timing oracle contract preserved", async () => {
|
||||
vi.mocked(prisma.userApiKey.findUnique).mockResolvedValue(null);
|
||||
const req = new Request("http://localhost/api/test", {
|
||||
headers: { authorization: "Bearer wwv_XXXXXXXX.fakesecret" },
|
||||
});
|
||||
const result = await authenticateApiKey(req);
|
||||
expect(result).toBeNull();
|
||||
// timingSafeEqual must have been called: both the miss path and the hit
|
||||
// path produce equal-length (32-byte) buffers from hex digests, so the
|
||||
// compare is well-defined and does not throw.
|
||||
});
|
||||
|
||||
it("hashedSecret is never returned to callers — result only contains userId and keyId", async () => {
|
||||
const { prefix, secret, hashedSecret } = generateApiKey();
|
||||
vi.mocked(prisma.userApiKey.findUnique).mockResolvedValue({
|
||||
id: "key-id-real",
|
||||
userId: "user-real",
|
||||
hashedSecret,
|
||||
} as never);
|
||||
vi.mocked(prisma.userApiKey.update).mockResolvedValue({} as never);
|
||||
|
||||
const req = new Request("http://localhost/api/test", {
|
||||
headers: { authorization: `Bearer ${prefix}.${secret}` },
|
||||
});
|
||||
const result = await authenticateApiKey(req);
|
||||
|
||||
expect(result).not.toBeNull();
|
||||
expect(result).not.toHaveProperty("hashedSecret");
|
||||
expect(result).not.toHaveProperty("secret");
|
||||
expect(Object.keys(result!)).toEqual(["userId", "keyId"]);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,136 @@
|
||||
import { randomBytes, createHmac, timingSafeEqual } from "crypto";
|
||||
import { prisma } from "@/lib/db";
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Signing key for HMAC-SHA256 hashing of API key secrets.
|
||||
// API_KEY_HMAC_SECRET is the preferred dedicated variable.
|
||||
// Falls back to AUTH_SECRET so local dev works without adding a new .env entry.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
function getSigningKey(): string {
|
||||
const key = process.env.API_KEY_HMAC_SECRET ?? process.env.AUTH_SECRET;
|
||||
if (!key) throw new Error("API_KEY_HMAC_SECRET (or AUTH_SECRET) must be set");
|
||||
return key;
|
||||
}
|
||||
|
||||
function hmacHex(secret: string): string {
|
||||
return createHmac("sha256", getSigningKey()).update(secret).digest("hex");
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// lastUsedAt throttle: at most one DB write per key per 60 seconds.
|
||||
// TTL-evict entries after 2x the window so this Map cannot grow unbounded.
|
||||
// Note: per-replica — at scale, move eviction to Redis.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
const lastUsedAtThrottle = new Map<string, number>();
|
||||
const LAST_USED_THROTTLE_MS = 60_000;
|
||||
const THROTTLE_TTL_MS = LAST_USED_THROTTLE_MS * 2;
|
||||
|
||||
function recordLastUsed(id: string): void {
|
||||
const now = Date.now();
|
||||
const lastWrite = lastUsedAtThrottle.get(id) ?? 0;
|
||||
|
||||
if (now - lastWrite <= LAST_USED_THROTTLE_MS) return;
|
||||
|
||||
lastUsedAtThrottle.set(id, now);
|
||||
|
||||
// Evict entries older than TTL to prevent unbounded growth
|
||||
for (const [key, ts] of lastUsedAtThrottle) {
|
||||
if (now - ts > THROTTLE_TTL_MS) lastUsedAtThrottle.delete(key);
|
||||
}
|
||||
|
||||
void prisma.userApiKey.update({
|
||||
where: { id },
|
||||
data: { lastUsedAt: new Date() },
|
||||
}).catch(() => { /* intentional — never block the request */ });
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Interfaces (exported for consumers — API-01)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
export interface GeneratedKey {
|
||||
/** e.g. "wwv_KpKF4LhL" — stored plaintext in DB as lookup handle */
|
||||
prefix: string;
|
||||
/** 32-byte base64url — shown to user ONCE, never stored */
|
||||
secret: string;
|
||||
/** HMAC-SHA256(signingKey, secret) hex — stored in DB */
|
||||
hashedSecret: string;
|
||||
/** "wwv_KpKF4LhL.3EqV...1k0" — the full bearer token, shown once */
|
||||
fullToken: string;
|
||||
}
|
||||
|
||||
export interface AuthenticatedKey {
|
||||
userId: string;
|
||||
keyId: string;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// generateApiKey — KEY-01, KEY-02
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Generates a new API key pair.
|
||||
* - prefix: "wwv_" + 8 url-safe chars (stored plaintext; used as DB lookup key)
|
||||
* - secret: 43 url-safe chars from 32 random bytes (returned ONCE, never stored)
|
||||
* - hashedSecret: HMAC-SHA256(signingKey, secret) hex — what gets persisted
|
||||
* - fullToken: combined bearer value shown to the user exactly once
|
||||
*/
|
||||
export function generateApiKey(): GeneratedKey {
|
||||
// randomBytes(6) -> 8 base64url chars (no padding)
|
||||
const prefix = "wwv_" + randomBytes(6).toString("base64url");
|
||||
// randomBytes(32) -> 43 base64url chars
|
||||
const secret = randomBytes(32).toString("base64url");
|
||||
const hashedSecret = hmacHex(secret);
|
||||
return {
|
||||
prefix,
|
||||
secret,
|
||||
hashedSecret,
|
||||
fullToken: `${prefix}.${secret}`,
|
||||
};
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// authenticateApiKey — API-01, KEY-02
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Resolves an "Authorization: Bearer wwv_<prefix>.<secret>" header to the
|
||||
* owning user. Returns null (never throws) on any failure path.
|
||||
*
|
||||
* Timing-oracle defense (T-16-01): timingSafeEqual always executes even
|
||||
* when the prefix is not found in the DB, using a dummy digest so the miss
|
||||
* path and the wrong-secret path are indistinguishable by latency.
|
||||
*/
|
||||
export async function authenticateApiKey(
|
||||
request: Request,
|
||||
): Promise<AuthenticatedKey | null> {
|
||||
const authHeader = request.headers.get("authorization");
|
||||
if (!authHeader?.startsWith("Bearer ")) return null;
|
||||
|
||||
const token = authHeader.slice(7).trim();
|
||||
const dotIdx = token.indexOf(".");
|
||||
if (dotIdx === -1) return null;
|
||||
|
||||
const prefix = token.substring(0, dotIdx);
|
||||
const secret = token.substring(dotIdx + 1);
|
||||
|
||||
const row = await prisma.userApiKey.findUnique({
|
||||
where: { prefix },
|
||||
select: { id: true, userId: true, hashedSecret: true },
|
||||
});
|
||||
|
||||
// Compute HMAC of the supplied secret, then compare with timingSafeEqual.
|
||||
// On a prefix miss we compare against a dummy digest — constant-work on
|
||||
// both paths defeats timing-oracle attacks (T-16-01).
|
||||
const supplied = Buffer.from(hmacHex(secret), "hex");
|
||||
const stored = Buffer.from(row?.hashedSecret ?? hmacHex("__wwv_dummy__"), "hex");
|
||||
const isValid = timingSafeEqual(supplied, stored);
|
||||
|
||||
if (!row || !isValid) return null;
|
||||
|
||||
recordLastUsed(row.id);
|
||||
|
||||
return { userId: row.userId, keyId: row.id };
|
||||
}
|
||||
@@ -0,0 +1,150 @@
|
||||
/**
|
||||
* Tests for the demo-admin identity persistence helpers in auth.ts.
|
||||
*
|
||||
* We test the exported pure functions directly rather than fighting the
|
||||
* NextAuth factory boundary. `persistDemoAdminIfNeeded` encapsulates the
|
||||
* jwt-callback guard logic and delegates to `ensureLocalUserPersisted`.
|
||||
*/
|
||||
import {
|
||||
describe, it, expect, vi, beforeEach
|
||||
} from "vitest";
|
||||
|
||||
// The global setup.ts mocks @/lib/auth entirely (to stop next-auth importing
|
||||
// next/server in jsdom). We need the real module here, so unmock it first.
|
||||
vi.unmock("@/lib/auth");
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Mock prisma before importing auth.ts so the module sees the mock.
|
||||
// vi.hoisted() runs before all vi.mock() factories, so the variable is
|
||||
// defined before the hoisted factory closure captures it.
|
||||
// ---------------------------------------------------------------------------
|
||||
const { mockUpsert } = vi.hoisted(() => ({
|
||||
mockUpsert: vi.fn().mockResolvedValue(undefined),
|
||||
}));
|
||||
|
||||
vi.mock("@/lib/db", () => ({
|
||||
prisma: {
|
||||
user: {
|
||||
upsert: mockUpsert,
|
||||
findFirst: vi.fn(),
|
||||
},
|
||||
},
|
||||
}));
|
||||
|
||||
// next-auth and its provider must be mocked to prevent NextAuth() runtime init.
|
||||
vi.mock("next-auth", () => ({
|
||||
default: vi.fn(() => ({
|
||||
handlers: {},
|
||||
auth: vi.fn(),
|
||||
signIn: vi.fn(),
|
||||
signOut: vi.fn(),
|
||||
})),
|
||||
}));
|
||||
vi.mock("next-auth/providers/credentials", () => ({
|
||||
default: vi.fn(() => ({ id: "credentials", name: "Credentials" })),
|
||||
}));
|
||||
vi.mock("@auth/supabase-adapter", () => ({
|
||||
SupabaseAdapter: vi.fn(() => ({})),
|
||||
}));
|
||||
vi.mock("@/lib/auth.config", () => ({
|
||||
authConfig: { callbacks: {}, providers: [] },
|
||||
}));
|
||||
vi.mock("@/core/edition", () => ({
|
||||
isCloud: false,
|
||||
isDemo: false,
|
||||
getDemoAdminSecret: vi.fn(() => undefined),
|
||||
DEMO_ADMIN_ROLE: "demo-admin",
|
||||
}));
|
||||
vi.mock("bcryptjs", () => ({ compareSync: vi.fn(() => false) }));
|
||||
|
||||
// Import after mocks.
|
||||
import {
|
||||
persistDemoAdminIfNeeded,
|
||||
ensureLocalUserPersisted,
|
||||
DEMO_ADMIN_ID,
|
||||
DEMO_ADMIN_EMAIL,
|
||||
DEMO_ADMIN_NAME,
|
||||
DEMO_ADMIN_PW_SENTINEL,
|
||||
} from "@/lib/auth";
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// ensureLocalUserPersisted
|
||||
// ---------------------------------------------------------------------------
|
||||
describe("ensureLocalUserPersisted", () => {
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
});
|
||||
|
||||
it("calls prisma.user.upsert with the supplied params", async () => {
|
||||
await ensureLocalUserPersisted({
|
||||
id: "user-abc",
|
||||
email: "[email protected]",
|
||||
name: "Test User",
|
||||
role: "user",
|
||||
hashedPassword: "$2b$10$fakehash",
|
||||
});
|
||||
|
||||
expect(mockUpsert).toHaveBeenCalledTimes(1);
|
||||
const call = mockUpsert.mock.calls[0][0];
|
||||
expect(call.where).toEqual({ id: "user-abc" });
|
||||
expect(call.create.hashedPassword).toBe("$2b$10$fakehash");
|
||||
expect(call.update).toEqual({});
|
||||
});
|
||||
|
||||
it("defaults hashedPassword to the sentinel when omitted", async () => {
|
||||
await ensureLocalUserPersisted({
|
||||
id: "demo-admin",
|
||||
email: DEMO_ADMIN_EMAIL,
|
||||
name: DEMO_ADMIN_NAME,
|
||||
role: "demo-admin",
|
||||
});
|
||||
|
||||
const call = mockUpsert.mock.calls[0][0];
|
||||
expect(call.create.hashedPassword).toBe(DEMO_ADMIN_PW_SENTINEL);
|
||||
// Sentinel must not look like a bcrypt hash -- bcrypt always starts with "$2"
|
||||
expect(DEMO_ADMIN_PW_SENTINEL.startsWith("$2")).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// persistDemoAdminIfNeeded
|
||||
// ---------------------------------------------------------------------------
|
||||
describe("persistDemoAdminIfNeeded -- jwt callback guard", () => {
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
});
|
||||
|
||||
it("calls ensureLocalUserPersisted with demo-admin constants on initial sign-in", async () => {
|
||||
await persistDemoAdminIfNeeded(DEMO_ADMIN_ID, false);
|
||||
|
||||
expect(mockUpsert).toHaveBeenCalledTimes(1);
|
||||
const call = mockUpsert.mock.calls[0][0];
|
||||
expect(call.where).toEqual({ id: DEMO_ADMIN_ID });
|
||||
expect(call.create.id).toBe(DEMO_ADMIN_ID);
|
||||
expect(call.create.email).toBe(DEMO_ADMIN_EMAIL);
|
||||
expect(call.create.name).toBe(DEMO_ADMIN_NAME);
|
||||
expect(call.create.role).toBe("demo-admin");
|
||||
expect(call.create.hashedPassword).toBe(DEMO_ADMIN_PW_SENTINEL);
|
||||
// idempotent upsert -- update must be empty
|
||||
expect(call.update).toEqual({});
|
||||
});
|
||||
|
||||
it("does NOT call upsert when isCloud is true", async () => {
|
||||
await persistDemoAdminIfNeeded(DEMO_ADMIN_ID, true);
|
||||
|
||||
expect(mockUpsert).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("does NOT call upsert for a non-demo-admin user id", async () => {
|
||||
await persistDemoAdminIfNeeded("regular-user-uuid", false);
|
||||
|
||||
expect(mockUpsert).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("does NOT call upsert when both cloud=true and id=demo-admin", async () => {
|
||||
// Cloud edition takes precedence even if the id somehow matches.
|
||||
await persistDemoAdminIfNeeded(DEMO_ADMIN_ID, true);
|
||||
|
||||
expect(mockUpsert).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
@@ -9,6 +9,65 @@ import {
|
||||
import { authConfig } from "@/lib/auth.config";
|
||||
import { SupabaseAdapter } from "@auth/supabase-adapter";
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Hardcoded constants for the demo-admin synthetic identity. These mirror the
|
||||
// values minted in authorize() and must never be derived from request input.
|
||||
// ---------------------------------------------------------------------------
|
||||
export const DEMO_ADMIN_ID = "demo-admin";
|
||||
export const DEMO_ADMIN_EMAIL = "[email protected]";
|
||||
export const DEMO_ADMIN_NAME = "Demo Admin";
|
||||
// Sentinel stored in hashedPassword for identities that never use bcrypt auth.
|
||||
// A bcrypt hash always starts with "$2", so this value can never match one and
|
||||
// compareSync against it always returns false -- the row cannot be used to log
|
||||
// in via the password flow.
|
||||
export const DEMO_ADMIN_PW_SENTINEL = "!demo-no-password";
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Upsert the local user row so that session.user.id always has a matching
|
||||
// `users` record, even after a DB reset or first-time setup. Scoped strictly
|
||||
// to non-cloud editions. We never create a user from untrusted input -- callers
|
||||
// must supply server-controlled constants only.
|
||||
// hashedPassword defaults to the sentinel for synthetic identities (demo-admin)
|
||||
// that authenticate via a separate mechanism and never use the password flow.
|
||||
// ---------------------------------------------------------------------------
|
||||
export async function ensureLocalUserPersisted(params: {
|
||||
id: string;
|
||||
email: string;
|
||||
name: string;
|
||||
role: string;
|
||||
hashedPassword?: string;
|
||||
}): Promise<void> {
|
||||
await prisma.user.upsert({
|
||||
where: { id: params.id },
|
||||
update: {},
|
||||
create: {
|
||||
id: params.id,
|
||||
email: params.email,
|
||||
name: params.name,
|
||||
role: params.role,
|
||||
hashedPassword: params.hashedPassword ?? DEMO_ADMIN_PW_SENTINEL,
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Exported for unit testing: handles the demo-admin upsert on initial sign-in.
|
||||
// Called from the jwt callback with `user` present (initial sign-in only).
|
||||
// Guards: non-cloud editions, demo-admin id only, server-controlled constants.
|
||||
// ---------------------------------------------------------------------------
|
||||
export async function persistDemoAdminIfNeeded(
|
||||
userId: string,
|
||||
cloudEdition: boolean,
|
||||
): Promise<void> {
|
||||
if (cloudEdition || userId !== DEMO_ADMIN_ID) return;
|
||||
await ensureLocalUserPersisted({
|
||||
id: DEMO_ADMIN_ID,
|
||||
email: DEMO_ADMIN_EMAIL,
|
||||
name: DEMO_ADMIN_NAME,
|
||||
role: DEMO_ADMIN_ROLE,
|
||||
});
|
||||
}
|
||||
|
||||
// Extract local credentials logic to a helper
|
||||
const localCredentialsProvider = Credentials({
|
||||
credentials: {
|
||||
@@ -43,6 +102,19 @@ const localCredentialsProvider = Credentials({
|
||||
const isValid = compareSync(password, user.hashedPassword);
|
||||
if (!isValid) return null;
|
||||
|
||||
// On the local edition, upsert the user row so that session.user.id
|
||||
// always corresponds to a real `users` record even after a DB reset.
|
||||
// Cloud users are managed by Supabase Auth (never reaches this branch).
|
||||
if (!isCloud) {
|
||||
await ensureLocalUserPersisted({
|
||||
id: user.id,
|
||||
email: user.email,
|
||||
name: user.name,
|
||||
role: user.role,
|
||||
hashedPassword: user.hashedPassword,
|
||||
});
|
||||
}
|
||||
|
||||
return {
|
||||
id: user.id,
|
||||
name: user.name,
|
||||
@@ -68,6 +140,11 @@ export const {
|
||||
if (user) {
|
||||
token.role = (user as { role?: string }).role ?? "user";
|
||||
token.id = user.id;
|
||||
// Persist the demo-admin synthetic identity on first sign-in so
|
||||
// that the `users` FK target exists for API key creation. Runs
|
||||
// only when `user` is present (initial sign-in, not token refresh).
|
||||
// All values inside come from server-controlled constants.
|
||||
await persistDemoAdminIfNeeded(user.id!, isCloud);
|
||||
}
|
||||
return token;
|
||||
},
|
||||
|
||||
@@ -0,0 +1,311 @@
|
||||
import {
|
||||
describe, it, expect, vi, beforeEach,
|
||||
} from "vitest";
|
||||
import type { GeoEntity } from "@worldwideview/wwv-plugin-sdk";
|
||||
import {
|
||||
searchEntities,
|
||||
getEntitiesInRegion,
|
||||
getEntityDetails,
|
||||
getPluginData,
|
||||
} from "@/lib/data-query/service";
|
||||
|
||||
// Module does not exist yet — this file is intentionally RED (Wave 0 TDD scaffold)
|
||||
|
||||
global.fetch = vi.fn();
|
||||
|
||||
beforeEach(() => {
|
||||
vi.resetAllMocks();
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Helpers
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
function makeEntity(overrides: Partial<GeoEntity> = {}): GeoEntity {
|
||||
return {
|
||||
id: "e1",
|
||||
pluginId: "test-plugin",
|
||||
latitude: 51.5,
|
||||
longitude: -0.1,
|
||||
timestamp: new Date(),
|
||||
properties: {},
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
function mockEngineSnapshot(pluginId: string, entities: GeoEntity[]): void {
|
||||
vi.mocked(global.fetch).mockResolvedValue(
|
||||
new Response(JSON.stringify({ items: entities }), { status: 200 }),
|
||||
);
|
||||
}
|
||||
|
||||
function mockEngine404(): void {
|
||||
vi.mocked(global.fetch).mockResolvedValue(
|
||||
new Response(null, { status: 404 }),
|
||||
);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// QUERY-01 — searchEntities
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("searchEntities", () => {
|
||||
it("returns [] for empty query string (no fetch called)", async () => {
|
||||
const results = await searchEntities("");
|
||||
expect(results).toEqual([]);
|
||||
expect(vi.mocked(global.fetch)).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("returns [] when engine returns 404 for plugin", async () => {
|
||||
mockEngine404();
|
||||
const results = await searchEntities("london", "test-plugin");
|
||||
expect(results).toEqual([]);
|
||||
});
|
||||
|
||||
it("returns matching entities for substring match on label", async () => {
|
||||
const entity = makeEntity({ id: "e1", label: "London Heathrow", pluginId: "test-plugin" });
|
||||
mockEngineSnapshot("test-plugin", [entity]);
|
||||
const results = await searchEntities("heathrow", "test-plugin");
|
||||
expect(results).toHaveLength(1);
|
||||
expect(results[0].id).toBe("e1");
|
||||
});
|
||||
|
||||
it("match is case-insensitive", async () => {
|
||||
const entity = makeEntity({ id: "e2", label: "PARIS CDG", pluginId: "test-plugin" });
|
||||
mockEngineSnapshot("test-plugin", [entity]);
|
||||
const results = await searchEntities("paris", "test-plugin");
|
||||
expect(results).toHaveLength(1);
|
||||
});
|
||||
|
||||
it("respects limit parameter (returns at most N results)", async () => {
|
||||
const entities = Array.from({ length: 10 }, (_, i) =>
|
||||
makeEntity({ id: `e${i}`, label: `entity ${i}`, pluginId: "test-plugin" }),
|
||||
);
|
||||
mockEngineSnapshot("test-plugin", entities);
|
||||
const results = await searchEntities("entity", "test-plugin", 3);
|
||||
expect(results.length).toBeLessThanOrEqual(3);
|
||||
});
|
||||
|
||||
it("restricts to pluginId when provided (fetch URL contains pluginId)", async () => {
|
||||
const entity = makeEntity({ id: "e3", label: "item", pluginId: "my-plugin" });
|
||||
mockEngineSnapshot("my-plugin", [entity]);
|
||||
await searchEntities("item", "my-plugin");
|
||||
const calledUrl = String(vi.mocked(global.fetch).mock.calls[0][0]);
|
||||
expect(calledUrl).toContain("my-plugin");
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// FILT-04 — searchEntities inline filters (on GeoEntity.properties, D-07)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("searchEntities filters", () => {
|
||||
it("returns only entities whose properties match the filter", async () => {
|
||||
const airborne = makeEntity({ id: "a1", label: "flight a1", pluginId: "flights", properties: { status: "airborne" } });
|
||||
const landed = makeEntity({ id: "a2", label: "flight a2", pluginId: "flights", properties: { status: "landed" } });
|
||||
mockEngineSnapshot("flights", [airborne, landed]);
|
||||
const results = await searchEntities("flight", "flights", 20, {
|
||||
status: { type: "select", values: ["airborne"] },
|
||||
});
|
||||
expect(results).toHaveLength(1);
|
||||
expect(results[0].id).toBe("a1");
|
||||
});
|
||||
|
||||
it("behaves identically when filters are omitted (no regression)", async () => {
|
||||
const e1 = makeEntity({ id: "b1", label: "flight b1", pluginId: "flights", properties: { status: "airborne" } });
|
||||
const e2 = makeEntity({ id: "b2", label: "flight b2", pluginId: "flights", properties: { status: "landed" } });
|
||||
mockEngineSnapshot("flights", [e1, e2]);
|
||||
const results = await searchEntities("flight", "flights", 20);
|
||||
expect(results).toHaveLength(2);
|
||||
});
|
||||
|
||||
it("excludes an entity missing the filtered property key", async () => {
|
||||
const withProp = makeEntity({ id: "c1", label: "flight c1", pluginId: "flights", properties: { status: "airborne" } });
|
||||
const missingProp = makeEntity({ id: "c2", label: "flight c2", pluginId: "flights", properties: {} });
|
||||
mockEngineSnapshot("flights", [withProp, missingProp]);
|
||||
const results = await searchEntities("flight", "flights", 20, {
|
||||
status: { type: "select", values: ["airborne"] },
|
||||
});
|
||||
expect(results).toHaveLength(1);
|
||||
expect(results[0].id).toBe("c1");
|
||||
});
|
||||
|
||||
it("limit counts only matching entities", async () => {
|
||||
const entities = Array.from({ length: 6 }, (_, i) =>
|
||||
makeEntity({
|
||||
id: `d${i}`,
|
||||
label: `flight d${i}`,
|
||||
pluginId: "flights",
|
||||
properties: { status: i % 2 === 0 ? "airborne" : "landed" },
|
||||
}),
|
||||
);
|
||||
mockEngineSnapshot("flights", entities);
|
||||
const results = await searchEntities("flight", "flights", 2, {
|
||||
status: { type: "select", values: ["airborne"] },
|
||||
});
|
||||
expect(results).toHaveLength(2);
|
||||
expect(results.every((r) => r.id.startsWith("d"))).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// QUERY-02 — getEntitiesInRegion
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("getEntitiesInRegion", () => {
|
||||
it("returns entities within bounding box", async () => {
|
||||
const entity = makeEntity({ id: "e1", latitude: 51.5, longitude: -0.1, pluginId: "test-plugin" });
|
||||
mockEngineSnapshot("test-plugin", [entity]);
|
||||
const results = await getEntitiesInRegion({
|
||||
north: 52,
|
||||
south: 50,
|
||||
east: 1,
|
||||
west: -1,
|
||||
pluginId: "test-plugin",
|
||||
});
|
||||
expect(results).toHaveLength(1);
|
||||
expect(results[0].id).toBe("e1");
|
||||
});
|
||||
|
||||
it("returns [] when no entities in region", async () => {
|
||||
const entity = makeEntity({ id: "e1", latitude: 10, longitude: 10, pluginId: "test-plugin" });
|
||||
mockEngineSnapshot("test-plugin", [entity]);
|
||||
const results = await getEntitiesInRegion({
|
||||
north: 52,
|
||||
south: 50,
|
||||
east: 1,
|
||||
west: -1,
|
||||
pluginId: "test-plugin",
|
||||
});
|
||||
expect(results).toEqual([]);
|
||||
});
|
||||
|
||||
it("handles antimeridian wraparound (east < west): entity at lon 175 inside bounds west:170 east:-170", async () => {
|
||||
const entity = makeEntity({ id: "e1", latitude: 0, longitude: 175, pluginId: "test-plugin" });
|
||||
mockEngineSnapshot("test-plugin", [entity]);
|
||||
const results = await getEntitiesInRegion({
|
||||
north: 10,
|
||||
south: -10,
|
||||
east: -170,
|
||||
west: 170,
|
||||
pluginId: "test-plugin",
|
||||
});
|
||||
expect(results).toHaveLength(1);
|
||||
expect(results[0].id).toBe("e1");
|
||||
});
|
||||
|
||||
it("respects pluginId filter", async () => {
|
||||
const entity = makeEntity({ id: "e1", latitude: 51.5, longitude: -0.1, pluginId: "specific-plugin" });
|
||||
mockEngineSnapshot("specific-plugin", [entity]);
|
||||
await getEntitiesInRegion({
|
||||
north: 52,
|
||||
south: 50,
|
||||
east: 1,
|
||||
west: -1,
|
||||
pluginId: "specific-plugin",
|
||||
});
|
||||
const calledUrl = String(vi.mocked(global.fetch).mock.calls[0][0]);
|
||||
expect(calledUrl).toContain("specific-plugin");
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// QUERY-03 — getEntityDetails
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("getEntityDetails", () => {
|
||||
it("returns DetailResult with all fields when entity found", async () => {
|
||||
const props = { speed: 250, airline: "BA" };
|
||||
const entity = makeEntity({
|
||||
id: "e1",
|
||||
pluginId: "test-plugin",
|
||||
latitude: 51.5,
|
||||
longitude: -0.1,
|
||||
label: "BA123",
|
||||
properties: props,
|
||||
});
|
||||
mockEngineSnapshot("test-plugin", [entity]);
|
||||
const result = await getEntityDetails("test-plugin", "e1");
|
||||
expect(result).not.toBeNull();
|
||||
expect(result?.id).toBe("e1");
|
||||
expect(result?.pluginId).toBe("test-plugin");
|
||||
expect(result?.latitude).toBe(51.5);
|
||||
expect(result?.longitude).toBe(-0.1);
|
||||
expect(result?.label).toBe("BA123");
|
||||
expect(result?.properties).toEqual(props);
|
||||
});
|
||||
|
||||
it("returns null when plugin returns 404", async () => {
|
||||
mockEngine404();
|
||||
const result = await getEntityDetails("test-plugin", "e1");
|
||||
expect(result).toBeNull();
|
||||
});
|
||||
|
||||
it("returns null when entityId not in snapshot", async () => {
|
||||
const entity = makeEntity({ id: "other-entity", pluginId: "test-plugin" });
|
||||
mockEngineSnapshot("test-plugin", [entity]);
|
||||
const result = await getEntityDetails("test-plugin", "e1");
|
||||
expect(result).toBeNull();
|
||||
});
|
||||
|
||||
it("returned properties includes original entity.properties object", async () => {
|
||||
const props = { foo: "bar", nested: { x: 1 } };
|
||||
const entity = makeEntity({ id: "e1", pluginId: "test-plugin", properties: props });
|
||||
mockEngineSnapshot("test-plugin", [entity]);
|
||||
const result = await getEntityDetails("test-plugin", "e1");
|
||||
expect(result?.properties).toEqual(props);
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// QUERY-04 — getPluginData
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("getPluginData", () => {
|
||||
it("returns PluginDataSnapshot with normalized entities when engine returns { items: [...] }", async () => {
|
||||
const entity = makeEntity({ id: "e1", pluginId: "test-plugin" });
|
||||
vi.mocked(global.fetch).mockResolvedValue(
|
||||
new Response(JSON.stringify({ items: [entity] }), { status: 200 }),
|
||||
);
|
||||
const snapshot = await getPluginData("test-plugin");
|
||||
expect(snapshot).not.toBeNull();
|
||||
expect(snapshot?.pluginId).toBe("test-plugin");
|
||||
expect(snapshot?.entities).toHaveLength(1);
|
||||
});
|
||||
|
||||
it("returns PluginDataSnapshot when engine returns flat array []", async () => {
|
||||
const entity = makeEntity({ id: "e1", pluginId: "test-plugin" });
|
||||
vi.mocked(global.fetch).mockResolvedValue(
|
||||
new Response(JSON.stringify([entity]), { status: 200 }),
|
||||
);
|
||||
const snapshot = await getPluginData("test-plugin");
|
||||
expect(snapshot).not.toBeNull();
|
||||
expect(snapshot?.entities).toHaveLength(1);
|
||||
});
|
||||
|
||||
it("returns null on engine 404", async () => {
|
||||
mockEngine404();
|
||||
const snapshot = await getPluginData("missing-plugin");
|
||||
expect(snapshot).toBeNull();
|
||||
});
|
||||
|
||||
it("returns null on engine non-2xx (500)", async () => {
|
||||
vi.mocked(global.fetch).mockResolvedValue(
|
||||
new Response(JSON.stringify({ error: "internal" }), { status: 500 }),
|
||||
);
|
||||
const snapshot = await getPluginData("test-plugin");
|
||||
expect(snapshot).toBeNull();
|
||||
});
|
||||
|
||||
it("normalizes timestamp string to Date object", async () => {
|
||||
const entityWithStringTimestamp = {
|
||||
...makeEntity({ id: "e1", pluginId: "test-plugin" }),
|
||||
timestamp: "2026-05-29T10:00:00Z",
|
||||
};
|
||||
vi.mocked(global.fetch).mockResolvedValue(
|
||||
new Response(JSON.stringify({ items: [entityWithStringTimestamp] }), { status: 200 }),
|
||||
);
|
||||
const snapshot = await getPluginData("test-plugin");
|
||||
expect(snapshot?.entities[0].timestamp).toBeInstanceOf(Date);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,198 @@
|
||||
import type { GeoEntity } from "@worldwideview/wwv-plugin-sdk";
|
||||
import type {
|
||||
SearchResult,
|
||||
RegionOptions,
|
||||
DetailResult,
|
||||
PluginDataSnapshot,
|
||||
} from "./types";
|
||||
import { matchFilterValue } from "@/core/filters/matchFilterValue";
|
||||
import type { FilterValue } from "@/core/plugins/PluginTypes";
|
||||
|
||||
function getEngineUrl(): string {
|
||||
return process.env.NEXT_PUBLIC_WWV_PLUGIN_DATA_ENGINE_URL ?? "http://localhost:5000";
|
||||
}
|
||||
|
||||
function normalizeEntity(raw: unknown): GeoEntity | null {
|
||||
if (typeof raw !== "object" || raw === null) return null;
|
||||
const e = raw as Record<string, unknown>;
|
||||
return {
|
||||
id: e.id as string,
|
||||
pluginId: e.pluginId as string,
|
||||
latitude: e.latitude as number,
|
||||
longitude: e.longitude as number,
|
||||
altitude: e.altitude as number | undefined,
|
||||
heading: e.heading as number | undefined,
|
||||
speed: e.speed as number | undefined,
|
||||
timestamp: new Date((e.timestamp as string | Date | undefined) ?? Date.now()),
|
||||
label: e.label as string | undefined,
|
||||
properties: (e.properties as Record<string, unknown>) ?? {},
|
||||
};
|
||||
}
|
||||
|
||||
/** Validate that a pluginId is safe to embed in a URL path segment. */
|
||||
function validatePluginId(pluginId: string): string {
|
||||
if (!/^[a-zA-Z0-9_-]+$/.test(pluginId)) {
|
||||
throw new Error("Invalid pluginId: only alphanumeric characters, hyphens, and underscores are allowed");
|
||||
}
|
||||
return pluginId;
|
||||
}
|
||||
|
||||
async function fetchPluginSnapshot(pluginId: string): Promise<PluginDataSnapshot | null> {
|
||||
const safeId = validatePluginId(pluginId);
|
||||
const engineBase = getEngineUrl();
|
||||
const url = new URL(`/api/${safeId}`, engineBase).toString();
|
||||
try {
|
||||
const res = await fetch(url, { signal: AbortSignal.timeout(5000) });
|
||||
if (res.status === 404) return null;
|
||||
if (!res.ok) {
|
||||
console.error("[data-query] Engine returned", res.status, "for plugin");
|
||||
return null;
|
||||
}
|
||||
const data: unknown = await res.json();
|
||||
const raw = Array.isArray(data) ? data : ((data as Record<string, unknown>)?.items ?? []) as unknown[];
|
||||
const entities: GeoEntity[] = (raw as unknown[]).reduce<GeoEntity[]>((acc, item) => {
|
||||
const entity = normalizeEntity(item);
|
||||
if (entity !== null) acc.push(entity);
|
||||
return acc;
|
||||
}, []);
|
||||
return { pluginId: safeId, entities, timestamp: new Date() };
|
||||
} catch (err) {
|
||||
console.error("[data-query] Failed to fetch plugin snapshot:", err);
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
async function getAllPluginSnapshots(): Promise<PluginDataSnapshot[]> {
|
||||
const url = `${getEngineUrl()}/manifest`;
|
||||
let pluginIds: string[] = [];
|
||||
try {
|
||||
const res = await fetch(url, { signal: AbortSignal.timeout(5000) });
|
||||
if (!res.ok) {
|
||||
console.error(`[data-query] Manifest fetch returned ${res.status}`);
|
||||
return [];
|
||||
}
|
||||
const data: unknown = await res.json();
|
||||
pluginIds = ((data as Record<string, unknown>)?.plugins as string[]) ?? [];
|
||||
} catch (err) {
|
||||
console.error("[data-query] Failed to fetch manifest:", err);
|
||||
return [];
|
||||
}
|
||||
|
||||
const results = await Promise.allSettled(pluginIds.map(fetchPluginSnapshot));
|
||||
return results.reduce<PluginDataSnapshot[]>((acc, result) => {
|
||||
if (result.status === "fulfilled" && result.value !== null) {
|
||||
acc.push(result.value);
|
||||
}
|
||||
return acc;
|
||||
}, []);
|
||||
}
|
||||
|
||||
function entityToSearchResult(entity: GeoEntity): SearchResult {
|
||||
return {
|
||||
id: entity.id,
|
||||
pluginId: entity.pluginId,
|
||||
name: entity.label ?? entity.id,
|
||||
latitude: entity.latitude,
|
||||
longitude: entity.longitude,
|
||||
};
|
||||
}
|
||||
|
||||
export async function searchEntities(
|
||||
query: string,
|
||||
pluginId?: string,
|
||||
limit: number = 20,
|
||||
filters?: Record<string, FilterValue>,
|
||||
): Promise<SearchResult[]> {
|
||||
const trimmed = query.trim();
|
||||
if (trimmed === "") return [];
|
||||
|
||||
const effectiveLimit = Math.min(Math.max(limit, 1), 100);
|
||||
const lower = trimmed.toLowerCase();
|
||||
const filterEntries = filters ? Object.entries(filters) : null;
|
||||
|
||||
const snapshots = pluginId
|
||||
? await fetchPluginSnapshot(pluginId).then((s) => (s ? [s] : []))
|
||||
: await getAllPluginSnapshots();
|
||||
|
||||
const results: SearchResult[] = [];
|
||||
for (const snapshot of snapshots) {
|
||||
for (const entity of snapshot.entities) {
|
||||
if (results.length >= effectiveLimit) break;
|
||||
const matchTarget = (entity.label ?? entity.id).toLowerCase();
|
||||
if (!matchTarget.includes(lower)) continue;
|
||||
// Apply inline filters on the full GeoEntity.properties BEFORE
|
||||
// entityToSearchResult conversion (which drops properties). D-07.
|
||||
if (filterEntries) {
|
||||
const ok = filterEntries.every(([key, fv]) =>
|
||||
matchFilterValue(entity.properties[key], fv),
|
||||
);
|
||||
if (!ok) continue;
|
||||
}
|
||||
results.push(entityToSearchResult(entity));
|
||||
}
|
||||
if (results.length >= effectiveLimit) break;
|
||||
}
|
||||
return results;
|
||||
}
|
||||
|
||||
export async function getEntitiesInRegion(bounds: RegionOptions): Promise<SearchResult[]> {
|
||||
const { north, south, east, west } = bounds;
|
||||
if (isNaN(north) || isNaN(south) || isNaN(east) || isNaN(west)) {
|
||||
throw new Error("Invalid bounding box: north/south/east/west must all be numbers");
|
||||
}
|
||||
|
||||
const effectiveLimit = Math.min(bounds.limit ?? 100, 1000);
|
||||
const isAntimeridian = east < west;
|
||||
|
||||
const snapshots = bounds.pluginId
|
||||
? await fetchPluginSnapshot(bounds.pluginId).then((s) => (s ? [s] : []))
|
||||
: await getAllPluginSnapshots();
|
||||
|
||||
const results: SearchResult[] = [];
|
||||
for (const snapshot of snapshots) {
|
||||
for (const entity of snapshot.entities) {
|
||||
if (results.length >= effectiveLimit) break;
|
||||
const { latitude: lat, longitude: lon } = entity;
|
||||
if (lat < south || lat > north) continue;
|
||||
const inLon = isAntimeridian
|
||||
? lon >= west || lon <= east
|
||||
: lon >= west && lon <= east;
|
||||
if (inLon) results.push(entityToSearchResult(entity));
|
||||
}
|
||||
if (results.length >= effectiveLimit) break;
|
||||
}
|
||||
return results;
|
||||
}
|
||||
|
||||
export async function getEntityDetails(
|
||||
pluginId: string,
|
||||
entityId: string,
|
||||
): Promise<DetailResult | null> {
|
||||
const snapshot = await fetchPluginSnapshot(pluginId);
|
||||
if (!snapshot) return null;
|
||||
|
||||
const entity = snapshot.entities.find((e) => e.id === entityId);
|
||||
if (!entity) return null;
|
||||
|
||||
return {
|
||||
id: entity.id,
|
||||
pluginId: entity.pluginId,
|
||||
latitude: entity.latitude,
|
||||
longitude: entity.longitude,
|
||||
altitude: entity.altitude,
|
||||
heading: entity.heading,
|
||||
speed: entity.speed,
|
||||
timestamp: entity.timestamp,
|
||||
label: entity.label,
|
||||
properties: entity.properties,
|
||||
};
|
||||
}
|
||||
|
||||
export async function getPluginData(pluginId: string): Promise<PluginDataSnapshot | null> {
|
||||
if (!pluginId.trim()) return null;
|
||||
try {
|
||||
return fetchPluginSnapshot(pluginId);
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,46 @@
|
||||
import type { GeoEntity } from "@worldwideview/wwv-plugin-sdk";
|
||||
import type { FilterValue } from "@/core/plugins/PluginTypes";
|
||||
|
||||
export interface SearchOptions {
|
||||
query: string;
|
||||
pluginId?: string;
|
||||
limit?: number;
|
||||
/** Optional inline filters keyed by entity property key (FILT-04, D-07). */
|
||||
filters?: Record<string, FilterValue>;
|
||||
}
|
||||
|
||||
export interface SearchResult {
|
||||
id: string;
|
||||
pluginId: string;
|
||||
name?: string;
|
||||
latitude: number;
|
||||
longitude: number;
|
||||
}
|
||||
|
||||
export interface RegionOptions {
|
||||
north: number;
|
||||
south: number;
|
||||
east: number;
|
||||
west: number;
|
||||
pluginId?: string;
|
||||
limit?: number;
|
||||
}
|
||||
|
||||
export interface DetailResult {
|
||||
id: string;
|
||||
pluginId: string;
|
||||
latitude: number;
|
||||
longitude: number;
|
||||
altitude?: number;
|
||||
heading?: number;
|
||||
speed?: number;
|
||||
timestamp: Date;
|
||||
label?: string;
|
||||
properties: Record<string, unknown>;
|
||||
}
|
||||
|
||||
export interface PluginDataSnapshot {
|
||||
pluginId: string;
|
||||
entities: GeoEntity[];
|
||||
timestamp: Date;
|
||||
}
|
||||
@@ -0,0 +1,65 @@
|
||||
import { describe, it, expect, vi, beforeEach } from "vitest";
|
||||
|
||||
vi.mock("@/lib/redis");
|
||||
|
||||
import { checkRateLimit } from "./geocodingRateLimit";
|
||||
import { redis } from "@/lib/redis";
|
||||
|
||||
const mockRedis = vi.mocked(redis, true);
|
||||
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
mockRedis.zremrangebyscore.mockResolvedValue(0);
|
||||
mockRedis.zadd.mockResolvedValue(1);
|
||||
mockRedis.expire.mockResolvedValue(1);
|
||||
});
|
||||
|
||||
describe("checkRateLimit", () => {
|
||||
it("resolves without error when zcard returns 1 (within limit of MAX_REQUESTS=1)", async () => {
|
||||
mockRedis.zcard.mockResolvedValue(1);
|
||||
|
||||
const result = await checkRateLimit("u1");
|
||||
|
||||
expect(result).toBeUndefined();
|
||||
});
|
||||
|
||||
it("returns rate_limited error object when zcard returns 2 (exceeds MAX_REQUESTS=1)", async () => {
|
||||
mockRedis.zcard.mockResolvedValue(2);
|
||||
|
||||
const result = await checkRateLimit("u1");
|
||||
|
||||
expect(result).toMatchObject({ error: "rate_limited" });
|
||||
});
|
||||
|
||||
it("calls zremrangebyscore to prune expired entries before checking count", async () => {
|
||||
mockRedis.zcard.mockResolvedValue(0);
|
||||
|
||||
await checkRateLimit("u1");
|
||||
|
||||
expect(mockRedis.zremrangebyscore).toHaveBeenCalledWith(
|
||||
expect.stringContaining("u1"),
|
||||
"-inf",
|
||||
expect.any(Number),
|
||||
);
|
||||
});
|
||||
|
||||
it("calls zadd to record the current request timestamp", async () => {
|
||||
mockRedis.zcard.mockResolvedValue(0);
|
||||
|
||||
await checkRateLimit("u1");
|
||||
|
||||
expect(mockRedis.zadd).toHaveBeenCalledWith(
|
||||
expect.stringContaining("u1"),
|
||||
expect.any(Number),
|
||||
expect.any(String),
|
||||
);
|
||||
});
|
||||
|
||||
it("calls expire(key, 5) to auto-expire the sorted set", async () => {
|
||||
mockRedis.zcard.mockResolvedValue(0);
|
||||
|
||||
await checkRateLimit("u1");
|
||||
|
||||
expect(mockRedis.expire).toHaveBeenCalledWith(expect.stringContaining("u1"), 5);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,49 @@
|
||||
/**
|
||||
* Per-user sliding-window rate limiter for geocoding (Phase 22 Wave 2 -- 22-02).
|
||||
*
|
||||
* Implements a Redis ZSET sliding window keyed per user. Each call prunes
|
||||
* entries older than WINDOW_MS, records the current request, bounds the key
|
||||
* lifetime, then counts. If the count exceeds MAX_REQUESTS the call is rejected.
|
||||
*
|
||||
* Best-effort (T-22-02-05): on any Redis error we fail OPEN (return undefined)
|
||||
* so a broken rate-limit check never causes a permanent geocoding outage. The
|
||||
* 1 req/sec limit is advisory, not a hard security boundary.
|
||||
*/
|
||||
|
||||
import { redis } from "@/lib/redis";
|
||||
|
||||
const WINDOW_MS = 1_000;
|
||||
const MAX_REQUESTS = 1;
|
||||
const KEY_TTL_SECONDS = 5;
|
||||
const RETRY_AFTER_MS = 1_000;
|
||||
|
||||
export interface RateLimitExceeded {
|
||||
error: "rate_limited";
|
||||
retryAfterMs: number;
|
||||
}
|
||||
|
||||
function rateKey(userId: string): string {
|
||||
return `nominatim:ratelimit:${userId}`;
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns `undefined` when the request is allowed, or a `rate_limited` result
|
||||
* object when the per-user window limit is exceeded.
|
||||
*/
|
||||
export async function checkRateLimit(userId: string): Promise<RateLimitExceeded | undefined> {
|
||||
const key = rateKey(userId);
|
||||
try {
|
||||
const now = Date.now();
|
||||
await redis.zremrangebyscore(key, "-inf", now - WINDOW_MS);
|
||||
await redis.zadd(key, now, String(now));
|
||||
await redis.expire(key, KEY_TTL_SECONDS);
|
||||
const count = await redis.zcard(key);
|
||||
if (count > MAX_REQUESTS) {
|
||||
return { error: "rate_limited", retryAfterMs: RETRY_AFTER_MS };
|
||||
}
|
||||
return undefined;
|
||||
} catch (err) {
|
||||
console.warn("[geocodingRateLimit] Redis error, failing open:", err);
|
||||
return undefined;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,311 @@
|
||||
/**
|
||||
* Tests for globeCommandQueue (Phase 19a Wave 0, updated for review fixes).
|
||||
*
|
||||
* QUEUE-01 enqueueGlobeCommand atomically rpush+expire via multi() chain
|
||||
* QUEUE-02 drainGlobeCommands atomically lranges + dels, returns parsed GlobeCommand[]
|
||||
* QUEUE-03 drainGlobeCommands drops invalid JSON and invalid command shapes silently
|
||||
* QUEUE-04 resolveActiveSessionId returns the newest session within 45s threshold
|
||||
* QUEUE-05 resolveActiveSessionId returns null when all sessions are older than 45s
|
||||
* QUEUE-06 setTimeline validation: invalid timeWindow and non-date currentTime are rejected
|
||||
*/
|
||||
|
||||
import { describe, it, expect, vi, beforeEach } from "vitest";
|
||||
import {
|
||||
enqueueGlobeCommand,
|
||||
drainGlobeCommands,
|
||||
resolveActiveSessionId,
|
||||
} from "./globeCommandQueue";
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Mock @/lib/redis
|
||||
// vi.mock is hoisted above variable declarations, so the mock objects must be
|
||||
// declared with vi.hoisted() to be accessible inside the factory function.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
const mockExecResult: [[null, string[]], [null, number]] = [
|
||||
[null, []],
|
||||
[null, 1],
|
||||
];
|
||||
|
||||
const { mockMultiChain, mockRedis } = vi.hoisted(() => {
|
||||
const mockMultiChain = {
|
||||
lrange: vi.fn().mockReturnThis(),
|
||||
del: vi.fn().mockReturnThis(),
|
||||
rpush: vi.fn().mockReturnThis(),
|
||||
expire: vi.fn().mockReturnThis(),
|
||||
exec: vi.fn(),
|
||||
};
|
||||
const mockRedis = {
|
||||
rpush: vi.fn(),
|
||||
expire: vi.fn(),
|
||||
zrange: vi.fn(),
|
||||
multi: vi.fn(() => mockMultiChain),
|
||||
};
|
||||
return { mockMultiChain, mockRedis };
|
||||
});
|
||||
|
||||
vi.mock("@/lib/redis", () => ({
|
||||
redis: mockRedis,
|
||||
}));
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Import after mocks
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
import type { GlobeCommand } from "@/core/globe/types/GlobeCommand";
|
||||
import { isValidGlobeCommand } from "@/core/globe/types/GlobeCommand";
|
||||
|
||||
beforeEach(() => {
|
||||
vi.resetAllMocks();
|
||||
// Re-wire multi chain after reset
|
||||
mockMultiChain.lrange.mockReturnThis();
|
||||
mockMultiChain.del.mockReturnThis();
|
||||
mockMultiChain.rpush.mockReturnThis();
|
||||
mockMultiChain.expire.mockReturnThis();
|
||||
mockMultiChain.exec.mockResolvedValue(mockExecResult);
|
||||
mockRedis.multi.mockReturnValue(mockMultiChain);
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// QUEUE-01: enqueueGlobeCommand — atomic multi() path
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("enqueueGlobeCommand (QUEUE-01)", () => {
|
||||
const panCmd: GlobeCommand = { type: "pan", lat: 1, lon: 2, alt: 3 };
|
||||
|
||||
it("calls multi().rpush(key, json).expire(key, ttl).exec() atomically", async () => {
|
||||
await enqueueGlobeCommand("u1", "s1", panCmd);
|
||||
|
||||
expect(mockRedis.multi).toHaveBeenCalledTimes(1);
|
||||
expect(mockMultiChain.rpush).toHaveBeenCalledWith(
|
||||
"globe:commandqueue:u1:s1",
|
||||
JSON.stringify(panCmd),
|
||||
);
|
||||
expect(mockMultiChain.expire).toHaveBeenCalledWith(
|
||||
"globe:commandqueue:u1:s1",
|
||||
expect.any(Number),
|
||||
);
|
||||
expect(mockMultiChain.exec).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
|
||||
it("uses a TTL in the range 55-120 seconds", async () => {
|
||||
await enqueueGlobeCommand("u1", "s1", panCmd);
|
||||
|
||||
const ttl = (mockMultiChain.expire.mock.calls[0] as [string, number])[1];
|
||||
expect(ttl).toBeGreaterThanOrEqual(55);
|
||||
expect(ttl).toBeLessThanOrEqual(120);
|
||||
});
|
||||
|
||||
it("scopes key to userId and sessionId independently", async () => {
|
||||
await enqueueGlobeCommand("alice", "sess-abc", panCmd);
|
||||
|
||||
expect(mockMultiChain.rpush).toHaveBeenCalledWith(
|
||||
"globe:commandqueue:alice:sess-abc",
|
||||
expect.any(String),
|
||||
);
|
||||
});
|
||||
|
||||
it("does NOT call rpush or expire directly on redis (atomic path only)", async () => {
|
||||
await enqueueGlobeCommand("u1", "s1", panCmd);
|
||||
|
||||
expect(mockRedis.rpush).not.toHaveBeenCalled();
|
||||
expect(mockRedis.expire).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// QUEUE-02: drainGlobeCommands -- happy path
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("drainGlobeCommands (QUEUE-02)", () => {
|
||||
const toggleCmd: GlobeCommand = { type: "toggleLayer", layerId: "ais" };
|
||||
const panCmd: GlobeCommand = { type: "pan", lat: 10, lon: 20, alt: 500 };
|
||||
|
||||
it("uses multi().lrange(key, 0, -1).del(key).exec() atomically", async () => {
|
||||
mockMultiChain.exec.mockResolvedValue([
|
||||
[null, [JSON.stringify(toggleCmd)]],
|
||||
[null, 1],
|
||||
]);
|
||||
|
||||
await drainGlobeCommands("u1", "s1");
|
||||
|
||||
expect(mockRedis.multi).toHaveBeenCalledTimes(1);
|
||||
expect(mockMultiChain.lrange).toHaveBeenCalledWith(
|
||||
"globe:commandqueue:u1:s1",
|
||||
0,
|
||||
-1,
|
||||
);
|
||||
expect(mockMultiChain.del).toHaveBeenCalledWith("globe:commandqueue:u1:s1");
|
||||
expect(mockMultiChain.exec).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
|
||||
it("returns an array of parsed GlobeCommands", async () => {
|
||||
mockMultiChain.exec.mockResolvedValue([
|
||||
[null, [JSON.stringify(panCmd), JSON.stringify(toggleCmd)]],
|
||||
[null, 1],
|
||||
]);
|
||||
|
||||
const result = await drainGlobeCommands("u1", "s1");
|
||||
|
||||
expect(result).toHaveLength(2);
|
||||
expect(result[0]).toEqual(panCmd);
|
||||
expect(result[1]).toEqual(toggleCmd);
|
||||
});
|
||||
|
||||
it("returns an empty array when the queue is empty", async () => {
|
||||
mockMultiChain.exec.mockResolvedValue([
|
||||
[null, []],
|
||||
[null, 0],
|
||||
]);
|
||||
|
||||
const result = await drainGlobeCommands("u1", "s1");
|
||||
|
||||
expect(result).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// QUEUE-03: drainGlobeCommands -- invalid entry filtering
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("drainGlobeCommands invalid entry filtering (QUEUE-03)", () => {
|
||||
it("silently drops entries that are invalid JSON", async () => {
|
||||
mockMultiChain.exec.mockResolvedValue([
|
||||
[null, ["not-json{{{", JSON.stringify({ type: "toggleLayer", layerId: "x" })]],
|
||||
[null, 1],
|
||||
]);
|
||||
|
||||
const result = await drainGlobeCommands("u1", "s1");
|
||||
|
||||
expect(result).toHaveLength(1);
|
||||
expect(result[0]).toEqual({ type: "toggleLayer", layerId: "x" });
|
||||
});
|
||||
|
||||
it("silently drops entries that fail the GlobeCommand shape check", async () => {
|
||||
const validCmd: GlobeCommand = { type: "pan", lat: 1, lon: 2, alt: 3 };
|
||||
mockMultiChain.exec.mockResolvedValue([
|
||||
[
|
||||
null,
|
||||
[
|
||||
JSON.stringify({ type: "unknown_type" }),
|
||||
JSON.stringify({ type: "pan", lat: "bad" }),
|
||||
JSON.stringify(validCmd),
|
||||
],
|
||||
],
|
||||
[null, 1],
|
||||
]);
|
||||
|
||||
const result = await drainGlobeCommands("u1", "s1");
|
||||
|
||||
expect(result).toHaveLength(1);
|
||||
expect(result[0]).toEqual(validCmd);
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// QUEUE-04 / QUEUE-05: resolveActiveSessionId
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("resolveActiveSessionId (QUEUE-04 / QUEUE-05)", () => {
|
||||
it("returns the newest session whose score is within 45s of Date.now()", async () => {
|
||||
const now = Date.now();
|
||||
const freshScore = now - 5_000; // 5s ago -- fresh
|
||||
const olderScore = now - 30_000; // 30s ago -- still fresh
|
||||
|
||||
// ioredis WITHSCORES flat interleaved array: [member, score, ...]
|
||||
mockRedis.zrange.mockResolvedValue([
|
||||
"sess-old", String(olderScore),
|
||||
"sess-new", String(freshScore),
|
||||
]);
|
||||
|
||||
const result = await resolveActiveSessionId("u1");
|
||||
|
||||
// Must return the newest (highest score = most recent)
|
||||
expect(result).toBe("sess-new");
|
||||
});
|
||||
|
||||
it("queries globe:sessions:{userId} with WITHSCORES", async () => {
|
||||
mockRedis.zrange.mockResolvedValue([]);
|
||||
|
||||
await resolveActiveSessionId("u1");
|
||||
|
||||
expect(mockRedis.zrange).toHaveBeenCalledWith(
|
||||
"globe:sessions:u1",
|
||||
expect.anything(),
|
||||
expect.anything(),
|
||||
"WITHSCORES",
|
||||
);
|
||||
});
|
||||
|
||||
it("returns null when the only entry is older than 45s", async () => {
|
||||
const now = Date.now();
|
||||
const staleScore = now - 60_000; // 60s ago -- stale
|
||||
|
||||
mockRedis.zrange.mockResolvedValue(["sess-stale", String(staleScore)]);
|
||||
|
||||
const result = await resolveActiveSessionId("u1");
|
||||
|
||||
expect(result).toBeNull();
|
||||
});
|
||||
|
||||
it("returns null when no sessions exist", async () => {
|
||||
mockRedis.zrange.mockResolvedValue([]);
|
||||
|
||||
const result = await resolveActiveSessionId("u1");
|
||||
|
||||
expect(result).toBeNull();
|
||||
});
|
||||
|
||||
it("returns null when all sessions are stale", async () => {
|
||||
const now = Date.now();
|
||||
mockRedis.zrange.mockResolvedValue([
|
||||
"sess-a", String(now - 50_000),
|
||||
"sess-b", String(now - 90_000),
|
||||
]);
|
||||
|
||||
const result = await resolveActiveSessionId("u1");
|
||||
|
||||
expect(result).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// QUEUE-06: setTimeline validation -- tightened timeWindow + currentTime checks
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("isValidGlobeCommand setTimeline validation (QUEUE-06)", () => {
|
||||
it("accepts a valid timeWindow value", () => {
|
||||
expect(isValidGlobeCommand({ type: "setTimeline", timeWindow: "24h" })).toBe(true);
|
||||
expect(isValidGlobeCommand({ type: "setTimeline", timeWindow: "1h" })).toBe(true);
|
||||
expect(isValidGlobeCommand({ type: "setTimeline", timeWindow: "7d" })).toBe(true);
|
||||
});
|
||||
|
||||
it("rejects an unrecognised timeWindow string", () => {
|
||||
expect(isValidGlobeCommand({ type: "setTimeline", timeWindow: "2d" })).toBe(false);
|
||||
expect(isValidGlobeCommand({ type: "setTimeline", timeWindow: "30m" })).toBe(false);
|
||||
expect(isValidGlobeCommand({ type: "setTimeline", timeWindow: "" })).toBe(false);
|
||||
});
|
||||
|
||||
it("accepts a valid ISO 8601 currentTime string", () => {
|
||||
expect(isValidGlobeCommand({ type: "setTimeline", currentTime: "2024-01-15T12:00:00Z" })).toBe(true);
|
||||
expect(isValidGlobeCommand({ type: "setTimeline", currentTime: "2024-01-15" })).toBe(true);
|
||||
});
|
||||
|
||||
it("rejects a currentTime that is not a parseable date", () => {
|
||||
expect(isValidGlobeCommand({ type: "setTimeline", currentTime: "not-a-date" })).toBe(false);
|
||||
expect(isValidGlobeCommand({ type: "setTimeline", currentTime: "25h" })).toBe(false);
|
||||
});
|
||||
|
||||
it("accepts setTimeline with no optional fields", () => {
|
||||
expect(isValidGlobeCommand({ type: "setTimeline" })).toBe(true);
|
||||
});
|
||||
|
||||
it("accepts setTimeline with all valid fields", () => {
|
||||
expect(isValidGlobeCommand({
|
||||
type: "setTimeline",
|
||||
currentTime: "2024-06-01T00:00:00Z",
|
||||
timeWindow: "6h",
|
||||
isPlaybackMode: true,
|
||||
})).toBe(true);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,87 @@
|
||||
import { redis } from "@/lib/redis";
|
||||
import { isValidGlobeCommand } from "@/core/globe/types/GlobeCommand";
|
||||
import type { GlobeCommand } from "@/core/globe/types/GlobeCommand";
|
||||
|
||||
const COMMAND_QUEUE_TTL_SECONDS = 60;
|
||||
const STALE_THRESHOLD_MS = 45_000;
|
||||
|
||||
function queueKey(userId: string, sessionId: string): string {
|
||||
return `globe:commandqueue:${userId}:${sessionId}`;
|
||||
}
|
||||
|
||||
export async function enqueueGlobeCommand(
|
||||
userId: string,
|
||||
sessionId: string,
|
||||
cmd: GlobeCommand,
|
||||
): Promise<void> {
|
||||
const key = queueKey(userId, sessionId);
|
||||
try {
|
||||
await redis.multi().rpush(key, JSON.stringify(cmd)).expire(key, COMMAND_QUEUE_TTL_SECONDS).exec();
|
||||
} catch (err) {
|
||||
console.error("[globeCommandQueue] enqueueGlobeCommand failed:", err);
|
||||
}
|
||||
}
|
||||
|
||||
export async function drainGlobeCommands(
|
||||
userId: string,
|
||||
sessionId: string,
|
||||
): Promise<GlobeCommand[]> {
|
||||
const key = queueKey(userId, sessionId);
|
||||
try {
|
||||
const results = await redis.multi().lrange(key, 0, -1).del(key).exec();
|
||||
|
||||
// results[0] is the lrange reply: [error | null, string[]]
|
||||
const lrangeReply = results[0];
|
||||
if (!lrangeReply || lrangeReply[0] !== null) {
|
||||
return [];
|
||||
}
|
||||
|
||||
const raw = lrangeReply[1];
|
||||
if (!Array.isArray(raw)) {
|
||||
return [];
|
||||
}
|
||||
|
||||
const commands: GlobeCommand[] = [];
|
||||
for (const entry of raw) {
|
||||
if (typeof entry !== "string") continue;
|
||||
try {
|
||||
const parsed: unknown = JSON.parse(entry);
|
||||
if (isValidGlobeCommand(parsed)) {
|
||||
commands.push(parsed);
|
||||
}
|
||||
} catch {
|
||||
// Drop unparseable entries silently
|
||||
}
|
||||
}
|
||||
|
||||
return commands;
|
||||
} catch (err) {
|
||||
console.error("[globeCommandQueue] drainGlobeCommands failed:", err);
|
||||
return [];
|
||||
}
|
||||
}
|
||||
|
||||
export async function resolveActiveSessionId(userId: string): Promise<string | null> {
|
||||
try {
|
||||
// ioredis WITHSCORES returns flat interleaved [member, score, member, score, ...]
|
||||
const flat = await redis.zrange(`globe:sessions:${userId}`, 0, -1, "WITHSCORES");
|
||||
const now = Date.now();
|
||||
|
||||
let bestMember: string | null = null;
|
||||
let bestScore = -Infinity;
|
||||
|
||||
for (let i = 0; i < flat.length; i += 2) {
|
||||
const member = flat[i];
|
||||
const score = Number(flat[i + 1]);
|
||||
if (now - score < STALE_THRESHOLD_MS && score > bestScore) {
|
||||
bestScore = score;
|
||||
bestMember = member;
|
||||
}
|
||||
}
|
||||
|
||||
return bestMember;
|
||||
} catch (err) {
|
||||
console.error("[globeCommandQueue] resolveActiveSessionId failed:", err);
|
||||
return null;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,168 @@
|
||||
import { describe, it, expect } from "vitest";
|
||||
import type { GeoEntity } from "@/core/plugins/PluginTypes";
|
||||
import type { LayerState } from "@/core/state/layersSlice";
|
||||
import { buildGlobeSnapshot } from "./globeState";
|
||||
|
||||
// Flat store shape — mirrors the live Zustand store (no nested state.globe.* namespace).
|
||||
// Only the fields buildGlobeSnapshot reads are included; the rest are omitted intentionally.
|
||||
const makeFakeState = (overrides: Partial<{
|
||||
cameraLat: number;
|
||||
cameraLon: number;
|
||||
cameraAlt: number;
|
||||
cameraHeading: number;
|
||||
cameraPitch: number;
|
||||
cameraRoll: number;
|
||||
layers: Record<string, LayerState>;
|
||||
currentTime: Date;
|
||||
timeWindow: string;
|
||||
isPlaybackMode: boolean;
|
||||
playbackTime: number;
|
||||
playbackSpeed: number;
|
||||
selectedEntity: GeoEntity | null;
|
||||
}> = {}) => ({
|
||||
cameraLat: 37.7749,
|
||||
cameraLon: -122.4194,
|
||||
cameraAlt: 500000,
|
||||
cameraHeading: 45,
|
||||
cameraPitch: -60,
|
||||
cameraRoll: 0,
|
||||
layers: {
|
||||
aviation: { enabled: true, entityCount: 42, loading: false },
|
||||
maritime: { enabled: false, entityCount: 0, loading: true },
|
||||
},
|
||||
currentTime: new Date("2026-01-15T12:00:00.000Z"),
|
||||
timeWindow: "24h",
|
||||
isPlaybackMode: false,
|
||||
playbackTime: 1737000000000,
|
||||
playbackSpeed: 1,
|
||||
selectedEntity: null as GeoEntity | null,
|
||||
...overrides,
|
||||
});
|
||||
|
||||
// RSRC-01 — buildGlobeSnapshot maps the flat store into a stable serializable shape.
|
||||
|
||||
describe("buildGlobeSnapshot — viewport mapping (RSRC-01)", () => {
|
||||
it("maps cameraLat/Lon/Alt/Heading/Pitch/Roll into viewport object", () => {
|
||||
const state = makeFakeState();
|
||||
const snapshot = buildGlobeSnapshot(state);
|
||||
|
||||
expect(snapshot.viewport).toEqual({
|
||||
lat: 37.7749,
|
||||
lon: -122.4194,
|
||||
altitude: 500000,
|
||||
heading: 45,
|
||||
pitch: -60,
|
||||
roll: 0,
|
||||
});
|
||||
});
|
||||
|
||||
it("preserves negative lat/lon values correctly", () => {
|
||||
const state = makeFakeState({ cameraLat: -33.8688, cameraLon: 151.2093, cameraAlt: 1000 });
|
||||
const snapshot = buildGlobeSnapshot(state);
|
||||
|
||||
expect(snapshot.viewport.lat).toBe(-33.8688);
|
||||
expect(snapshot.viewport.lon).toBe(151.2093);
|
||||
expect(snapshot.viewport.altitude).toBe(1000);
|
||||
});
|
||||
});
|
||||
|
||||
describe("buildGlobeSnapshot — layers passthrough (RSRC-01)", () => {
|
||||
it("passes layers Record through unchanged", () => {
|
||||
const layers = {
|
||||
aviation: { enabled: true, entityCount: 42, loading: false },
|
||||
maritime: { enabled: false, entityCount: 0, loading: true },
|
||||
};
|
||||
const state = makeFakeState({ layers });
|
||||
const snapshot = buildGlobeSnapshot(state);
|
||||
|
||||
expect(snapshot.layers).toEqual(layers);
|
||||
});
|
||||
|
||||
it("handles empty layers Record", () => {
|
||||
const state = makeFakeState({ layers: {} });
|
||||
const snapshot = buildGlobeSnapshot(state);
|
||||
|
||||
expect(snapshot.layers).toEqual({});
|
||||
});
|
||||
});
|
||||
|
||||
describe("buildGlobeSnapshot — timeline serialization (RSRC-01)", () => {
|
||||
it("serializes currentTime as an ISO string", () => {
|
||||
const date = new Date("2026-01-15T12:00:00.000Z");
|
||||
const state = makeFakeState({ currentTime: date });
|
||||
const snapshot = buildGlobeSnapshot(state);
|
||||
|
||||
expect(snapshot.timeline.currentTime).toBe("2026-01-15T12:00:00.000Z");
|
||||
});
|
||||
|
||||
it("includes timeWindow in timeline", () => {
|
||||
const state = makeFakeState({ timeWindow: "6h" });
|
||||
const snapshot = buildGlobeSnapshot(state);
|
||||
|
||||
expect(snapshot.timeline.timeWindow).toBe("6h");
|
||||
});
|
||||
|
||||
it("includes isPlaybackMode in timeline", () => {
|
||||
const state = makeFakeState({ isPlaybackMode: true });
|
||||
const snapshot = buildGlobeSnapshot(state);
|
||||
|
||||
expect(snapshot.timeline.isPlaybackMode).toBe(true);
|
||||
});
|
||||
|
||||
it("includes playbackTime in timeline", () => {
|
||||
const state = makeFakeState({ playbackTime: 1737000000000 });
|
||||
const snapshot = buildGlobeSnapshot(state);
|
||||
|
||||
expect(snapshot.timeline.playbackTime).toBe(1737000000000);
|
||||
});
|
||||
|
||||
it("includes playbackSpeed in timeline", () => {
|
||||
const state = makeFakeState({ playbackSpeed: 10 });
|
||||
const snapshot = buildGlobeSnapshot(state);
|
||||
|
||||
expect(snapshot.timeline.playbackSpeed).toBe(10);
|
||||
});
|
||||
});
|
||||
|
||||
describe("buildGlobeSnapshot — selectedEntity (RSRC-01)", () => {
|
||||
it("returns null for selectedEntity when state.selectedEntity is null", () => {
|
||||
const state = makeFakeState({ selectedEntity: null });
|
||||
const snapshot = buildGlobeSnapshot(state);
|
||||
|
||||
expect(snapshot.selectedEntity).toBeNull();
|
||||
});
|
||||
|
||||
it("returns 'pluginId:id' string when a GeoEntity is selected", () => {
|
||||
const entity: GeoEntity = {
|
||||
id: "icao-abc123",
|
||||
pluginId: "aviation",
|
||||
latitude: 40.7128,
|
||||
longitude: -74.006,
|
||||
timestamp: new Date(),
|
||||
properties: {},
|
||||
};
|
||||
const state = makeFakeState({ selectedEntity: entity });
|
||||
const snapshot = buildGlobeSnapshot(state);
|
||||
|
||||
expect(snapshot.selectedEntity).toBe("aviation:icao-abc123");
|
||||
});
|
||||
});
|
||||
|
||||
describe("buildGlobeSnapshot — lastUpdate (RSRC-01)", () => {
|
||||
it("lastUpdate is a number (Unix timestamp ms)", () => {
|
||||
const state = makeFakeState();
|
||||
const snapshot = buildGlobeSnapshot(state);
|
||||
|
||||
expect(typeof snapshot.lastUpdate).toBe("number");
|
||||
});
|
||||
|
||||
it("lastUpdate is approximately now (within 1 second)", () => {
|
||||
const before = Date.now();
|
||||
const state = makeFakeState();
|
||||
const snapshot = buildGlobeSnapshot(state);
|
||||
const after = Date.now();
|
||||
|
||||
expect(snapshot.lastUpdate).toBeGreaterThanOrEqual(before);
|
||||
expect(snapshot.lastUpdate).toBeLessThanOrEqual(after);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,66 @@
|
||||
import type { GeoEntity } from "@/core/plugins/PluginTypes";
|
||||
import type { LayerState } from "@/core/state/layersSlice";
|
||||
|
||||
export interface GlobeViewport {
|
||||
lat: number;
|
||||
lon: number;
|
||||
altitude: number;
|
||||
heading: number;
|
||||
pitch: number;
|
||||
roll: number;
|
||||
}
|
||||
|
||||
export interface GlobeStateSnapshot {
|
||||
viewport: GlobeViewport;
|
||||
layers: Record<string, LayerState>;
|
||||
timeline: {
|
||||
currentTime: string;
|
||||
timeWindow: string;
|
||||
isPlaybackMode: boolean;
|
||||
playbackTime: number;
|
||||
playbackSpeed: number;
|
||||
};
|
||||
selectedEntity: string | null;
|
||||
lastUpdate: number;
|
||||
}
|
||||
|
||||
export interface AppStoreSnapshotInput {
|
||||
cameraLat: number;
|
||||
cameraLon: number;
|
||||
cameraAlt: number;
|
||||
cameraHeading: number;
|
||||
cameraPitch: number;
|
||||
cameraRoll: number;
|
||||
layers: Record<string, LayerState>;
|
||||
currentTime: Date;
|
||||
timeWindow: string;
|
||||
isPlaybackMode: boolean;
|
||||
playbackTime: number;
|
||||
playbackSpeed: number;
|
||||
selectedEntity: GeoEntity | null;
|
||||
}
|
||||
|
||||
export function buildGlobeSnapshot(state: AppStoreSnapshotInput): GlobeStateSnapshot {
|
||||
return {
|
||||
viewport: {
|
||||
lat: state.cameraLat,
|
||||
lon: state.cameraLon,
|
||||
altitude: state.cameraAlt,
|
||||
heading: state.cameraHeading,
|
||||
pitch: state.cameraPitch,
|
||||
roll: state.cameraRoll,
|
||||
},
|
||||
layers: state.layers,
|
||||
timeline: {
|
||||
currentTime: state.currentTime.toISOString(),
|
||||
timeWindow: state.timeWindow,
|
||||
isPlaybackMode: state.isPlaybackMode,
|
||||
playbackTime: state.playbackTime,
|
||||
playbackSpeed: state.playbackSpeed,
|
||||
},
|
||||
selectedEntity: state.selectedEntity
|
||||
? `${state.selectedEntity.pluginId}:${state.selectedEntity.id}`
|
||||
: null,
|
||||
lastUpdate: Date.now(),
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,199 @@
|
||||
import { describe, it, expect, vi, beforeEach } from "vitest";
|
||||
import {
|
||||
writeGlobeState,
|
||||
readGlobeState,
|
||||
readActiveSessions,
|
||||
globeStateKey,
|
||||
globeSessionsKey,
|
||||
} from "./globeStateStore";
|
||||
import { redis } from "@/lib/redis";
|
||||
|
||||
vi.mock("@/lib/redis", () => ({
|
||||
redis: {
|
||||
set: vi.fn(),
|
||||
get: vi.fn(),
|
||||
zadd: vi.fn(),
|
||||
zrange: vi.fn(),
|
||||
zrem: vi.fn(),
|
||||
},
|
||||
}));
|
||||
|
||||
const mockRedis = vi.mocked(redis);
|
||||
|
||||
beforeEach(() => {
|
||||
vi.resetAllMocks();
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Key helpers
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("globeStateKey", () => {
|
||||
it("returns 'globe:state:{userId}:{sessionId}'", () => {
|
||||
expect(globeStateKey("u1", "s1")).toBe("globe:state:u1:s1");
|
||||
});
|
||||
});
|
||||
|
||||
describe("globeSessionsKey", () => {
|
||||
it("returns 'globe:sessions:{userId}'", () => {
|
||||
expect(globeSessionsKey("u1")).toBe("globe:sessions:u1");
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// writeGlobeState (RSRC-01)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("writeGlobeState (RSRC-01)", () => {
|
||||
const fakeSnapshot = {
|
||||
viewport: { lat: 37.7, lon: -122.4, altitude: 500000, heading: 0, pitch: -90, roll: 0 },
|
||||
layers: { aviation: { enabled: true, entityCount: 5, loading: false } },
|
||||
timeline: {
|
||||
currentTime: "2026-01-15T12:00:00.000Z",
|
||||
timeWindow: "24h",
|
||||
isPlaybackMode: false,
|
||||
playbackTime: 1737000000000,
|
||||
playbackSpeed: 1,
|
||||
},
|
||||
selectedEntity: null,
|
||||
lastUpdate: Date.now(),
|
||||
};
|
||||
|
||||
it("calls redis.set with the state key, JSON-serialized snapshot, and EX 30 TTL", async () => {
|
||||
mockRedis.set.mockResolvedValue("OK");
|
||||
mockRedis.zadd.mockResolvedValue(1);
|
||||
|
||||
await writeGlobeState("u1", "s1", fakeSnapshot);
|
||||
|
||||
expect(mockRedis.set).toHaveBeenCalledWith(
|
||||
"globe:state:u1:s1",
|
||||
JSON.stringify(fakeSnapshot),
|
||||
"EX",
|
||||
30,
|
||||
);
|
||||
});
|
||||
|
||||
it("calls redis.zadd with sessions key, a numeric score, and sessionId", async () => {
|
||||
mockRedis.set.mockResolvedValue("OK");
|
||||
mockRedis.zadd.mockResolvedValue(1);
|
||||
|
||||
await writeGlobeState("u1", "s1", fakeSnapshot);
|
||||
|
||||
const [key, score, member] = mockRedis.zadd.mock.calls[0] as [string, number, string];
|
||||
expect(key).toBe("globe:sessions:u1");
|
||||
expect(typeof score).toBe("number");
|
||||
expect(member).toBe("s1");
|
||||
});
|
||||
|
||||
it("resolves (fire-and-forget) even when redis.set rejects", async () => {
|
||||
mockRedis.set.mockRejectedValue(new Error("Redis connection refused"));
|
||||
mockRedis.zadd.mockResolvedValue(1);
|
||||
|
||||
await expect(writeGlobeState("u1", "s1", fakeSnapshot)).resolves.not.toThrow();
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// readGlobeState (RSRC-02)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("readGlobeState (RSRC-02)", () => {
|
||||
const storedSnapshot = {
|
||||
viewport: { lat: 10, lon: 20, altitude: 100000, heading: 0, pitch: -90, roll: 0 },
|
||||
layers: {},
|
||||
timeline: {
|
||||
currentTime: "2026-01-15T12:00:00.000Z",
|
||||
timeWindow: "1h",
|
||||
isPlaybackMode: false,
|
||||
playbackTime: 1737000000000,
|
||||
playbackSpeed: 1,
|
||||
},
|
||||
selectedEntity: null,
|
||||
lastUpdate: 1737000000000,
|
||||
};
|
||||
|
||||
it("returns the parsed snapshot when redis.get resolves a JSON string", async () => {
|
||||
mockRedis.get.mockResolvedValue(JSON.stringify(storedSnapshot));
|
||||
|
||||
const result = await readGlobeState("u1", "s1");
|
||||
|
||||
expect(result).toEqual(storedSnapshot);
|
||||
});
|
||||
|
||||
it("returns null when redis.get resolves null (key expired or not found)", async () => {
|
||||
mockRedis.get.mockResolvedValue(null);
|
||||
|
||||
const result = await readGlobeState("u1", "s1");
|
||||
|
||||
expect(result).toBeNull();
|
||||
});
|
||||
|
||||
it("queries the correct key", async () => {
|
||||
mockRedis.get.mockResolvedValue(null);
|
||||
|
||||
await readGlobeState("u1", "s1");
|
||||
|
||||
expect(mockRedis.get).toHaveBeenCalledWith("globe:state:u1:s1");
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// readActiveSessions (RSRC-03)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("readActiveSessions (RSRC-03)", () => {
|
||||
it("returns only sessions whose score is within the 45s staleness threshold", async () => {
|
||||
const now = Date.now();
|
||||
const freshScore = now;
|
||||
const staleScore = now - 60_000; // 60s ago — beyond the 45s threshold
|
||||
|
||||
// ioredis WITHSCORES returns flat interleaved [member, score, member, score, ...]
|
||||
mockRedis.zrange.mockResolvedValue([
|
||||
"fresh",
|
||||
String(freshScore),
|
||||
"stale",
|
||||
String(staleScore),
|
||||
]);
|
||||
mockRedis.zrem.mockResolvedValue(1);
|
||||
|
||||
const sessions = await readActiveSessions("u1");
|
||||
|
||||
const ids = sessions.map((s) => s.sessionId);
|
||||
expect(ids).toContain("fresh");
|
||||
expect(ids).not.toContain("stale");
|
||||
});
|
||||
|
||||
it("each entry has { sessionId, lastSeen } shape", async () => {
|
||||
const now = Date.now();
|
||||
mockRedis.zrange.mockResolvedValue(["sess-a", String(now)]);
|
||||
mockRedis.zrem.mockResolvedValue(0);
|
||||
|
||||
const sessions = await readActiveSessions("u1");
|
||||
|
||||
expect(sessions).toHaveLength(1);
|
||||
expect(sessions[0]).toHaveProperty("sessionId", "sess-a");
|
||||
expect(sessions[0]).toHaveProperty("lastSeen");
|
||||
expect(typeof sessions[0].lastSeen).toBe("number");
|
||||
});
|
||||
|
||||
it("returns empty array when no sessions exist", async () => {
|
||||
mockRedis.zrange.mockResolvedValue([]);
|
||||
|
||||
const sessions = await readActiveSessions("u1");
|
||||
|
||||
expect(sessions).toEqual([]);
|
||||
});
|
||||
|
||||
it("scopes the ZSET query to the correct sessions key", async () => {
|
||||
mockRedis.zrange.mockResolvedValue([]);
|
||||
|
||||
await readActiveSessions("u1");
|
||||
|
||||
expect(mockRedis.zrange).toHaveBeenCalledWith(
|
||||
"globe:sessions:u1",
|
||||
expect.anything(),
|
||||
expect.anything(),
|
||||
expect.anything(),
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,70 @@
|
||||
import { redis } from "@/lib/redis";
|
||||
import type { GlobeStateSnapshot } from "@/lib/globeState";
|
||||
|
||||
const STATE_TTL_SECONDS = 30;
|
||||
const STALE_THRESHOLD_MS = 45_000;
|
||||
|
||||
export function globeStateKey(userId: string, sessionId: string): string {
|
||||
return `globe:state:${userId}:${sessionId}`;
|
||||
}
|
||||
|
||||
export function globeSessionsKey(userId: string): string {
|
||||
return `globe:sessions:${userId}`;
|
||||
}
|
||||
|
||||
export async function writeGlobeState(
|
||||
userId: string,
|
||||
sessionId: string,
|
||||
snapshot: GlobeStateSnapshot,
|
||||
): Promise<void> {
|
||||
try {
|
||||
await redis.set(globeStateKey(userId, sessionId), JSON.stringify(snapshot), "EX", STATE_TTL_SECONDS);
|
||||
await redis.zadd(globeSessionsKey(userId), Date.now(), sessionId);
|
||||
} catch (err) {
|
||||
console.warn("[globeStateStore] writeGlobeState failed:", err);
|
||||
}
|
||||
}
|
||||
|
||||
export async function readGlobeState(
|
||||
userId: string,
|
||||
sessionId: string,
|
||||
): Promise<GlobeStateSnapshot | null> {
|
||||
try {
|
||||
const raw = await redis.get(globeStateKey(userId, sessionId));
|
||||
if (raw === null) return null;
|
||||
return JSON.parse(raw) as GlobeStateSnapshot;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
export async function readActiveSessions(
|
||||
userId: string,
|
||||
): Promise<Array<{ sessionId: string; lastSeen: number }>> {
|
||||
try {
|
||||
// ioredis WITHSCORES returns flat interleaved [member, score, member, score, ...]
|
||||
const flat = await redis.zrange(globeSessionsKey(userId), 0, -1, "WITHSCORES");
|
||||
const now = Date.now();
|
||||
const active: Array<{ sessionId: string; lastSeen: number }> = [];
|
||||
const stale: string[] = [];
|
||||
|
||||
for (let i = 0; i < flat.length; i += 2) {
|
||||
const member = flat[i];
|
||||
const score = Number(flat[i + 1]);
|
||||
if (now - score < STALE_THRESHOLD_MS) {
|
||||
active.push({ sessionId: member, lastSeen: score });
|
||||
} else {
|
||||
stale.push(member);
|
||||
}
|
||||
}
|
||||
|
||||
// Best-effort stale cleanup — never blocks or throws
|
||||
if (stale.length > 0) {
|
||||
redis.zrem(globeSessionsKey(userId), ...stale).catch(() => undefined);
|
||||
}
|
||||
|
||||
return active;
|
||||
} catch {
|
||||
return [];
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,14 @@
|
||||
/**
|
||||
* Shared Zod coordinate schemas for MCP tool input validation.
|
||||
*
|
||||
* z.number() already rejects NaN (Zod coerces the raw input and NaN fails
|
||||
* the number check). .finite() additionally rejects Infinity/-Infinity.
|
||||
* Both checks are independent; .finite() does NOT cover NaN.
|
||||
*/
|
||||
|
||||
import { z } from "zod";
|
||||
|
||||
export const latSchema = z.number().min(-90).max(90);
|
||||
export const lonSchema = z.number().min(-180).max(180);
|
||||
// altitude must be a positive finite number
|
||||
export const altSchema = z.number().gt(0).finite();
|
||||
@@ -0,0 +1,16 @@
|
||||
/**
|
||||
* Shared Zod filter-value schema for MCP tool input validation.
|
||||
*
|
||||
* A strict discriminated union on `type` so structurally invalid filter values
|
||||
* are rejected at the tool boundary (T-23-01-02 tampering mitigation). Reused by
|
||||
* filterTools.ts (set_filter) and search_entities in tools.ts.
|
||||
*/
|
||||
|
||||
import { z } from "zod";
|
||||
|
||||
export const filterValueSchema = z.discriminatedUnion("type", [
|
||||
z.object({ type: z.literal("text"), value: z.string() }),
|
||||
z.object({ type: z.literal("select"), values: z.array(z.string()) }),
|
||||
z.object({ type: z.literal("range"), min: z.number(), max: z.number() }),
|
||||
z.object({ type: z.literal("boolean"), value: z.boolean() }),
|
||||
]);
|
||||
@@ -0,0 +1,266 @@
|
||||
/**
|
||||
* RED tests for pluginTools (Phase 21 Wave 0).
|
||||
*
|
||||
* These tests INTENTIONALLY FAIL because src/lib/mcp/pluginTools.ts does not exist yet.
|
||||
* Wave 1 creates getNamespacedTools and the minimal input validator.
|
||||
*
|
||||
* PT-01 getNamespacedTools: auto-namespaces each tool to {pluginId}__{name}
|
||||
* PT-02 getNamespacedTools: preserves description, inputSchema, capabilities per tool
|
||||
* PT-03 getNamespacedTools: duplicate raw names across plugins stay distinct after namespacing
|
||||
* PT-04 Minimal validator: accepts args matching a schema (type/required/enum)
|
||||
* PT-05 Minimal validator: rejects args missing a required key
|
||||
* PT-06 Minimal validator: rejects args with wrong primitive type
|
||||
* PT-07 Minimal validator: rejects values outside an enum
|
||||
* PT-08 Minimal validator: uses no external schema library (hand-rolled)
|
||||
*/
|
||||
|
||||
import { describe, it, expect } from "vitest";
|
||||
import { getNamespacedTools, validateToolArgs } from "@/lib/mcp/pluginTools";
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Types (mirrors what Wave 1 will export from pluginTools.ts)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/** Shape of a namespaced tool entry returned by getNamespacedTools. */
|
||||
interface NamespacedTool {
|
||||
namespacedName: string;
|
||||
pluginId: string;
|
||||
description: string;
|
||||
inputSchema: Record<string, unknown>;
|
||||
}
|
||||
|
||||
/** Shape of the result returned by validateToolArgs. */
|
||||
interface ValidationResult {
|
||||
valid: boolean;
|
||||
errors: string[];
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Fixtures
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/** A minimal McpToolDeclaration fixture (v3 -- no execution field). */
|
||||
function toolDecl(name: string, description = "A tool.") {
|
||||
return {
|
||||
name,
|
||||
description,
|
||||
inputSchema: {
|
||||
type: "object" as const,
|
||||
properties: {
|
||||
code: { type: "string" },
|
||||
count: { type: "number" },
|
||||
mode: { type: "string", enum: ["fast", "slow"] },
|
||||
},
|
||||
required: ["code"],
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
/** A minimal plugin fixture that carries mcpTools. */
|
||||
function pluginEntry(pluginId: string, tools: ReturnType<typeof toolDecl>[]) {
|
||||
return { pluginId, mcpTools: tools };
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// PT-01: auto-namespacing
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("getNamespacedTools namespacing (PT-01)", () => {
|
||||
it("namespaces each tool to {pluginId}__{name}", () => {
|
||||
const plugins = [pluginEntry("aviation", [toolDecl("decode_squawk")])];
|
||||
const result = getNamespacedTools(plugins);
|
||||
|
||||
expect(result).toHaveLength(1);
|
||||
expect(result[0].namespacedName).toBe("aviation__decode_squawk");
|
||||
});
|
||||
|
||||
it("namespaces tools from multiple plugins independently", () => {
|
||||
const plugins = [
|
||||
pluginEntry("aviation", [toolDecl("decode_squawk")]),
|
||||
pluginEntry("maritime", [toolDecl("decode_mmsi")]),
|
||||
];
|
||||
const result = getNamespacedTools(plugins) as NamespacedTool[];
|
||||
|
||||
expect(result).toHaveLength(2);
|
||||
const names = result.map((t) => t.namespacedName);
|
||||
expect(names).toContain("aviation__decode_squawk");
|
||||
expect(names).toContain("maritime__decode_mmsi");
|
||||
});
|
||||
|
||||
it("handles a plugin with multiple tools", () => {
|
||||
const plugins = [
|
||||
pluginEntry("aviation", [toolDecl("decode_squawk"), toolDecl("lookup_flight")]),
|
||||
];
|
||||
const result = getNamespacedTools(plugins);
|
||||
|
||||
expect(result).toHaveLength(2);
|
||||
expect(result[0].namespacedName).toBe("aviation__decode_squawk");
|
||||
expect(result[1].namespacedName).toBe("aviation__lookup_flight");
|
||||
});
|
||||
|
||||
it("returns an empty array when no plugins have mcpTools", () => {
|
||||
const result = getNamespacedTools([]);
|
||||
expect(result).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// PT-02: preserves tool metadata
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("getNamespacedTools metadata preservation (PT-02)", () => {
|
||||
it("preserves description on the namespaced tool entry", () => {
|
||||
const plugins = [pluginEntry("aviation", [toolDecl("decode_squawk", "Squawk decoder.")])];
|
||||
const result = getNamespacedTools(plugins);
|
||||
|
||||
expect(result[0].description).toBe("Squawk decoder.");
|
||||
});
|
||||
|
||||
it("preserves inputSchema on the namespaced tool entry", () => {
|
||||
const plugins = [pluginEntry("aviation", [toolDecl("decode_squawk")])];
|
||||
const result = getNamespacedTools(plugins);
|
||||
|
||||
expect(result[0].inputSchema).toMatchObject({ type: "object" });
|
||||
});
|
||||
|
||||
it("carries the source pluginId on the namespaced tool entry", () => {
|
||||
const plugins = [pluginEntry("aviation", [toolDecl("decode_squawk")])];
|
||||
const result = getNamespacedTools(plugins);
|
||||
|
||||
expect(result[0].pluginId).toBe("aviation");
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// PT-03: duplicate raw names across plugins stay distinct after namespacing
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("getNamespacedTools deduplication across plugins (PT-03)", () => {
|
||||
it("keeps tools distinct when two plugins use the same raw tool name", () => {
|
||||
const plugins = [
|
||||
pluginEntry("aviation", [toolDecl("get_info")]),
|
||||
pluginEntry("maritime", [toolDecl("get_info")]),
|
||||
];
|
||||
const result = getNamespacedTools(plugins) as NamespacedTool[];
|
||||
|
||||
expect(result).toHaveLength(2);
|
||||
const names = result.map((t) => t.namespacedName);
|
||||
expect(names).toContain("aviation__get_info");
|
||||
expect(names).toContain("maritime__get_info");
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// PT-04: minimal validator -- accepts valid args
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("validateToolArgs accepts valid args (PT-04)", () => {
|
||||
const schema = {
|
||||
type: "object" as const,
|
||||
properties: {
|
||||
code: { type: "string" },
|
||||
count: { type: "number" },
|
||||
mode: { type: "string", enum: ["fast", "slow"] },
|
||||
},
|
||||
required: ["code"],
|
||||
};
|
||||
|
||||
it("accepts args where required keys are present with correct types", () => {
|
||||
const result = validateToolArgs({ code: "7700" }, schema);
|
||||
expect(result.valid).toBe(true);
|
||||
expect(result.errors).toHaveLength(0);
|
||||
});
|
||||
|
||||
it("accepts args that include optional keys with correct types", () => {
|
||||
const result = validateToolArgs({ code: "7700", count: 3, mode: "fast" }, schema);
|
||||
expect(result.valid).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// PT-05: missing required key
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("validateToolArgs rejects missing required key (PT-05)", () => {
|
||||
const schema = {
|
||||
type: "object" as const,
|
||||
properties: {
|
||||
code: { type: "string" },
|
||||
},
|
||||
required: ["code"],
|
||||
};
|
||||
|
||||
it("rejects args when a required property is absent", () => {
|
||||
const result = validateToolArgs({}, schema) as ValidationResult;
|
||||
expect(result.valid).toBe(false);
|
||||
expect(result.errors.some((e: string) => /code/i.test(e))).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// PT-06: wrong primitive type
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("validateToolArgs rejects wrong primitive type (PT-06)", () => {
|
||||
const schema = {
|
||||
type: "object" as const,
|
||||
properties: {
|
||||
code: { type: "string" },
|
||||
count: { type: "number" },
|
||||
},
|
||||
required: ["code", "count"],
|
||||
};
|
||||
|
||||
it("rejects a string where a number is expected", () => {
|
||||
const result = validateToolArgs({ code: "7700", count: "not-a-number" }, schema) as ValidationResult;
|
||||
expect(result.valid).toBe(false);
|
||||
expect(result.errors.some((e: string) => /count/i.test(e))).toBe(true);
|
||||
});
|
||||
|
||||
it("rejects a number where a string is expected", () => {
|
||||
const result = validateToolArgs({ code: 123, count: 5 }, schema) as ValidationResult;
|
||||
expect(result.valid).toBe(false);
|
||||
expect(result.errors.some((e: string) => /code/i.test(e))).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// PT-07: enum validation
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("validateToolArgs rejects values outside enum (PT-07)", () => {
|
||||
const schema = {
|
||||
type: "object" as const,
|
||||
properties: {
|
||||
mode: { type: "string", enum: ["fast", "slow"] },
|
||||
},
|
||||
required: ["mode"],
|
||||
};
|
||||
|
||||
it("accepts a value that is in the enum", () => {
|
||||
const result = validateToolArgs({ mode: "fast" }, schema);
|
||||
expect(result.valid).toBe(true);
|
||||
});
|
||||
|
||||
it("rejects a value that is not in the enum", () => {
|
||||
const result = validateToolArgs({ mode: "turbo" }, schema) as ValidationResult;
|
||||
expect(result.valid).toBe(false);
|
||||
expect(result.errors.some((e: string) => /mode/i.test(e))).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// PT-08: no external schema library (hand-rolled)
|
||||
// This is a design assertion: the import above must come from a local module
|
||||
// that does not re-export zod, ajv, or any schema library.
|
||||
// Tested implicitly by the import path pointing to our own module.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("validateToolArgs hand-rolled (PT-08)", () => {
|
||||
it("validateToolArgs is exported from the local pluginTools module, not a schema lib", () => {
|
||||
// If the import at the top of this file resolves, the module exists.
|
||||
// This test will fail (RED) until Wave 1 creates src/lib/mcp/pluginTools.ts.
|
||||
expect(typeof validateToolArgs).toBe("function");
|
||||
expect(typeof getNamespacedTools).toBe("function");
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,174 @@
|
||||
/**
|
||||
* @file pluginTools.ts
|
||||
* @description Server-side helpers for plugin-declared MCP tools (Phase 21 Wave 1).
|
||||
*
|
||||
* Responsibilities:
|
||||
* - getNamespacedTools: collect tool declarations from plugins, auto-namespace
|
||||
* each to `{pluginId}__{name}` so names are globally unique.
|
||||
* - validateToolArgs: a minimal hand-rolled validator (type / required / enum)
|
||||
* that rejects bad input before the server enqueues a tool invocation.
|
||||
*
|
||||
* Design constraints (v3 frontend-relay):
|
||||
* - No external schema library (no zod, no ajv) -- hand-rolled only.
|
||||
* - McpToolDeclaration has NO `execution` field; the browser executes tools.
|
||||
* - This file is server-side only; no React / Cesium imports.
|
||||
*/
|
||||
|
||||
import type { McpToolDeclaration } from "@/core/plugins/PluginManifest";
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Types
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Minimal input schema shape used by McpToolDeclaration.
|
||||
* Only the subset the validator checks (type / properties / required / enum).
|
||||
*/
|
||||
export interface ToolInputSchema {
|
||||
type: "object";
|
||||
properties?: Record<string, PropertySchema>;
|
||||
required?: string[];
|
||||
}
|
||||
|
||||
/** Schema for a single property inside a ToolInputSchema. */
|
||||
export interface PropertySchema {
|
||||
type: string;
|
||||
enum?: string[];
|
||||
}
|
||||
|
||||
/**
|
||||
* A plugin entry as required by getNamespacedTools.
|
||||
* Only the fields this helper reads are required.
|
||||
*/
|
||||
export interface PluginToolsEntry {
|
||||
pluginId: string;
|
||||
mcpTools?: McpToolDeclaration[];
|
||||
mcpCapabilities?: string[];
|
||||
}
|
||||
|
||||
/** A fully-resolved, namespaced tool ready for inclusion in tools/list. */
|
||||
export interface NamespacedTool {
|
||||
/** The globally-unique tool name: `{pluginId}__{name}`. */
|
||||
namespacedName: string;
|
||||
/** The plugin that declared this tool. */
|
||||
pluginId: string;
|
||||
/** Human-readable description forwarded from the declaration. */
|
||||
description: string;
|
||||
/** Input schema forwarded from the declaration. */
|
||||
inputSchema: Record<string, unknown>;
|
||||
/**
|
||||
* Opaque capability tags declared by the source plugin.
|
||||
* Forwarded from PluginManifest.mcpCapabilities.
|
||||
*/
|
||||
capabilities: string[];
|
||||
}
|
||||
|
||||
/** Result of a validateToolArgs call. */
|
||||
export interface ToolValidationResult {
|
||||
valid: boolean;
|
||||
errors: string[];
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// getNamespacedTools
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Collect MCP tool declarations from a set of plugins and auto-namespace each
|
||||
* tool name to `{pluginId}__{name}`.
|
||||
*
|
||||
* Duplicate raw names across different plugins remain distinct because the
|
||||
* namespace prefix is always the plugin ID.
|
||||
*
|
||||
* @param plugins - Array of plugin entries (id + optional mcpTools + mcpCapabilities).
|
||||
* @returns Flat list of namespaced tool entries.
|
||||
*/
|
||||
export function getNamespacedTools(plugins: PluginToolsEntry[]): NamespacedTool[] {
|
||||
const result: NamespacedTool[] = [];
|
||||
|
||||
for (const plugin of plugins) {
|
||||
if (!plugin.mcpTools || plugin.mcpTools.length === 0) {
|
||||
continue;
|
||||
}
|
||||
|
||||
const capabilities = plugin.mcpCapabilities ?? [];
|
||||
|
||||
for (const tool of plugin.mcpTools) {
|
||||
result.push({
|
||||
namespacedName: `${plugin.pluginId}__${tool.name}`,
|
||||
pluginId: plugin.pluginId,
|
||||
description: tool.description,
|
||||
inputSchema: tool.inputSchema as Record<string, unknown>,
|
||||
capabilities,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
return result;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// validateToolArgs (hand-rolled, no external schema library)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Validate tool invocation arguments against a minimal input schema.
|
||||
*
|
||||
* Checks performed (in order):
|
||||
* 1. Required keys must be present.
|
||||
* 2. Present keys must have the correct primitive type.
|
||||
* 3. Keys with an `enum` constraint must match one of the allowed values.
|
||||
*
|
||||
* This validator REJECTS bad input -- it does NOT coerce or default values.
|
||||
* It is the server-side gate before enqueue (Wave 3 dependency).
|
||||
*
|
||||
* @param args - The raw arguments from the MCP client.
|
||||
* @param schema - The ToolInputSchema from the McpToolDeclaration.
|
||||
* @returns { valid, errors } -- errors is empty when valid is true.
|
||||
*/
|
||||
export function validateToolArgs(
|
||||
args: Record<string, unknown>,
|
||||
schema: ToolInputSchema,
|
||||
): ToolValidationResult {
|
||||
const errors: string[] = [];
|
||||
const properties = schema.properties ?? {};
|
||||
const required = schema.required ?? [];
|
||||
|
||||
// 1. Check required keys
|
||||
for (const key of required) {
|
||||
if (!(key in args) || args[key] === undefined || args[key] === null) {
|
||||
errors.push(`Missing required argument: "${key}"`);
|
||||
}
|
||||
}
|
||||
|
||||
// 2. Type check + enum check for all present keys that have a schema
|
||||
for (const [key, propSchema] of Object.entries(properties)) {
|
||||
if (!(key in args)) {
|
||||
// Not present and not required -- skip
|
||||
continue;
|
||||
}
|
||||
|
||||
const value = args[key];
|
||||
|
||||
// 2a. Primitive type check
|
||||
// typeof null === "object", so guard null explicitly
|
||||
if (value === null || typeof value !== propSchema.type) {
|
||||
errors.push(
|
||||
`Argument "${key}" must be of type ${propSchema.type}, got ${value === null ? "null" : typeof value}`,
|
||||
);
|
||||
// Skip enum check when type is already wrong
|
||||
continue;
|
||||
}
|
||||
|
||||
// 2b. Enum check (only when the property declares an enum)
|
||||
if (propSchema.enum && propSchema.enum.length > 0) {
|
||||
if (!propSchema.enum.includes(value as string)) {
|
||||
errors.push(
|
||||
`Argument "${key}" must be one of [${propSchema.enum.map((v) => `"${v}"`).join(", ")}], got "${String(value)}"`,
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return { valid: errors.length === 0, errors };
|
||||
}
|
||||
@@ -0,0 +1,78 @@
|
||||
/**
|
||||
* Tests for the MCP server factory (src/lib/mcp/server.ts).
|
||||
*
|
||||
* SRV-01 MCP_SERVER_INSTRUCTIONS is exported and contains "globe://sessions"
|
||||
* SRV-02 createMcpServer() passes a non-empty instructions string to McpServer
|
||||
* SRV-03 The instructions passed to McpServer contain "globe://sessions"
|
||||
* SRV-04 createMcpServer() also passes capabilities with tools.listChanged: true
|
||||
*/
|
||||
|
||||
import { describe, it, expect, vi, beforeEach } from "vitest";
|
||||
|
||||
// vi.mock is hoisted above all imports by Vitest, so we cannot reference
|
||||
// module-scope variables inside the factory. Use vi.fn() inline and retrieve
|
||||
// the spy via vi.mocked() after the import is resolved.
|
||||
vi.mock("@modelcontextprotocol/sdk/server/mcp.js", () => ({
|
||||
McpServer: vi.fn(function McpServerMock(this: unknown) {
|
||||
return {
|
||||
connect: vi.fn().mockResolvedValue(undefined),
|
||||
registerResource: vi.fn(),
|
||||
registerTool: vi.fn(),
|
||||
};
|
||||
}),
|
||||
}));
|
||||
|
||||
// Imports resolved AFTER the mock factory above is registered.
|
||||
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
||||
import { createMcpServer, MCP_SERVER_INSTRUCTIONS } from "@/lib/mcp/server";
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Tests
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("MCP_SERVER_INSTRUCTIONS export", () => {
|
||||
it("SRV-01: is a non-empty string that mentions globe://sessions", () => {
|
||||
expect(typeof MCP_SERVER_INSTRUCTIONS).toBe("string");
|
||||
expect(MCP_SERVER_INSTRUCTIONS.length).toBeGreaterThan(0);
|
||||
expect(MCP_SERVER_INSTRUCTIONS).toContain("globe://sessions");
|
||||
});
|
||||
});
|
||||
|
||||
describe("createMcpServer()", () => {
|
||||
beforeEach(() => {
|
||||
vi.mocked(McpServer).mockClear();
|
||||
});
|
||||
|
||||
it("SRV-02: passes a non-empty instructions string as the second arg", () => {
|
||||
createMcpServer();
|
||||
expect(vi.mocked(McpServer)).toHaveBeenCalledOnce();
|
||||
// mock.calls is typed as unknown[][], route through unknown to narrow safely.
|
||||
const call = vi.mocked(McpServer).mock.calls[0] as unknown as [
|
||||
unknown,
|
||||
{ instructions?: string },
|
||||
];
|
||||
const options = call[1];
|
||||
expect(typeof options?.instructions).toBe("string");
|
||||
expect((options?.instructions ?? "").length).toBeGreaterThan(0);
|
||||
});
|
||||
|
||||
it("SRV-03: instructions mention globe://sessions", () => {
|
||||
createMcpServer();
|
||||
const call = vi.mocked(McpServer).mock.calls[0] as unknown as [
|
||||
unknown,
|
||||
{ instructions?: string },
|
||||
];
|
||||
const options = call[1];
|
||||
expect(options?.instructions).toContain("globe://sessions");
|
||||
});
|
||||
|
||||
it("SRV-04: capabilities include tools.listChanged: true", () => {
|
||||
createMcpServer();
|
||||
const call = vi.mocked(McpServer).mock.calls[0] as unknown as [
|
||||
unknown,
|
||||
{ capabilities?: { tools?: { listChanged?: boolean } } },
|
||||
];
|
||||
const options = call[1];
|
||||
expect(options?.capabilities?.tools?.listChanged).toBe(true);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,72 @@
|
||||
/**
|
||||
* MCP server factory -- Phase 17 (Stateless Streamable HTTP transport)
|
||||
*
|
||||
* createMcpServer() returns a FRESH McpServer instance on every call.
|
||||
* It is the single aggregation point where future phases register their
|
||||
* capabilities:
|
||||
*
|
||||
* Phase 18 -- registerGlobeResources(server, { userId }) -> globe:// resources
|
||||
* Phase 19 -- registerGlobeCommandTools(server, { userId }) -> globe control tools
|
||||
* Phase 20 -- registerDataQueryTools(server, { userId }) -> data query tools
|
||||
* Phase 21 -- dynamic per-plugin tools merged into tools/list
|
||||
*
|
||||
* Those registrars are NOT called here -- Phase 17 ships the transport only.
|
||||
* Each feature phase calls its own registrar from src/app/api/mcp/route.ts
|
||||
* AFTER createMcpServer() returns, passing { userId } via closure injection
|
||||
* (per RECONCILIATION R-1).
|
||||
*
|
||||
* Stateless invariant (D-17-04): never cache this instance. A fresh server
|
||||
* is created per request so no session state or transport binding leaks
|
||||
* between concurrent requests.
|
||||
*/
|
||||
|
||||
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
||||
|
||||
const SERVER_NAME = "worldwideview" as const;
|
||||
|
||||
// The MCP server's own protocol-advertised version. Bump this when the
|
||||
// server's self-description or tool surface changes in a meaningful way.
|
||||
// This is NOT package.json -- do not keep them in sync automatically.
|
||||
export const MCP_SERVER_VERSION = "1.3.0" as const;
|
||||
|
||||
export const MCP_SERVER_INSTRUCTIONS = `\
|
||||
WorldWideView MCP server. Read and control a live 3D geospatial globe for the authenticated user. Everything is scoped to your API key: you only ever see and control your own data and your own browser sessions.
|
||||
|
||||
CAPABILITIES
|
||||
- Globe command tools (write/steer a live browser tab): pan_globe, focus_entity, toggle_layer, set_timeline.
|
||||
- Data query tools (read shared engine data): search_entities, get_entities_in_region, get_entity_details, get_plugin_data.
|
||||
- Resources (read): globe://sessions, globe://state/{sessionId}, globe://layers.
|
||||
- Plugin tools (dynamic): extra tools named "<pluginId>__<toolName>" appear only after a browser tab has loaded that plugin and published its catalog. Re-call tools/list after the relevant plugin is loaded.
|
||||
|
||||
SESSIONS (read before using any command tool)
|
||||
- A session is one open browser tab showing the globe, identified by a UUID sessionId.
|
||||
- To discover sessions, READ the resource globe://sessions. It returns the tabs active in the last ~45 seconds; a tab that goes quiet drops off the list.
|
||||
- Every command tool takes an optional sessionId. Omit it to target your most-recently-active tab. Pass a sessionId from globe://sessions to target one specific tab. Commands are isolated per session and are never broadcast to other tabs.
|
||||
- To see what a specific tab currently shows (camera, layers, timeline), read globe://state/{sessionId}.
|
||||
- If no tab is active, command tools return "no active globe session to control" -- the user must open the app in a browser first.
|
||||
|
||||
COORDINATES
|
||||
- latitude must be in [-90, 90], longitude in [-180, 180], altitude greater than 0 metres. Out-of-range values are rejected with a validation error.
|
||||
|
||||
DATA AVAILABILITY
|
||||
- Data query tools return {"success": true, "entities": [], "count": 0} when nothing matches OR when the live data engine is not currently feeding that plugin. An empty result is normal, not an error.`;
|
||||
|
||||
/**
|
||||
* Returns a fresh, empty-capability McpServer per call.
|
||||
*
|
||||
* STATELESS (D-17-04): never cache this instance; a fresh server is created
|
||||
* per request. Do NOT hoist the return value to module scope.
|
||||
*/
|
||||
export function createMcpServer(): McpServer {
|
||||
return new McpServer(
|
||||
{ name: SERVER_NAME, version: MCP_SERVER_VERSION },
|
||||
{
|
||||
instructions: MCP_SERVER_INSTRUCTIONS,
|
||||
capabilities: {
|
||||
// tools.listChanged: required so Phase 21 can push live tool
|
||||
// list updates to clients (RECONCILIATION R-1).
|
||||
tools: { listChanged: true },
|
||||
},
|
||||
},
|
||||
);
|
||||
}
|
||||
Loaded 100 of 114 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user