vantage-peers-mcp 2.4.12 → 2.4.14

package/CHANGELOG.md

@@ -1,10 +1,29 @@
 # Changelog
 
-## [2.4.0] — 2026-05-28 — M3 iframeEmbedSessions + __VP_TOOL_RESULT__ stream marker + ack-checklist
+## [2.4.13] — 2026-06-02 — Post-public republish: attribution + CHANGELOG day-numbers + RULE #7 narrative scrub
+
+Repository visibility flip to PUBLIC on 2026-06-02 (mission D62 `k57e4t21sr55rhz8ng554eseb987wvh3`). This patch republishes the npm package so the published README + CHANGELOG + attribution match the now-public source.
+
+No runtime / API / schema changes. Documentation + metadata only.
+
+What changed since v2.4.12:
+- `mcp-server/package.json`: author restructured to "VantageOS AI Orchestrator Team" with contributors block (Pi, Laurent Perello, ElPi Corp). Dependency `@vantageos/mosaic@^0.1.2` added for Phase 1 Mosaic groundwork (PR #605, server-side createMosaicResource API ready for Phase 2 primitive swap).
+- `mcp-server/CHANGELOG.md`: version headers simplified to `X.Y.Z — YYYY-MM-DD` (Day N anchors dropped per Laurent verdict 2026-06-02 — dates are self-explanatory, day numbers added noise). Narrative client-name mentions (Marie/Iris RH/Cédric Delport) genericized to "early-access RH cohort" / "self-host incident" per RULE #7 pre-public scrub.
+- Root README rework (PR #611 + PR #610 + PR #616 chain): TL;DR + Mermaid architecture diagram + 5 hero features + 22-features collapsed details + 84-tools 8-groups + Backend: Convex 3-paths + attribution Credits section. README /team 404 hotfix landed in PR #616.
+
+Merged PRs in this republish window:
+- PR #611 (`9464f9a`) — T5ter README rework + CHANGELOG day-numbers + attribution
+- PR #615 (`c189a1d`) — Phase 1 RULE #7 pre-public scrub
+- PR #616 (`99eeae5`) — README /team 404 hotfix
+
+Mission: D62 pre-public cleanup `k57e4t21sr55rhz8ng554eseb987wvh3`.
+Friction capitalize: `post-public-flip-must-trigger-npm-republish-for-consistency-not-just-repo-visibility-flip` + `day-79-hook-should-validate-tree-not-commit-sha`.
+
+## [2.4.0] — 2026-05-29 — M3 iframeEmbedSessions + __VP_TOOL_RESULT__ stream marker + ack-checklist
 
 **Mission instance** : `sigma-vantage-peers-mcp-gui-iframe-embed-v1` (k5730xct6rvrwkvxhy5t5js12d87jwfw).
 **Pi sign-off** : PI_AUTHORIZED_TASK_ID=`k1793m1qgn0zaay6r87dhvsh7187kwya` (PROD-DEPLOY-AUTHORIZED).
-**Eta sign-off** : ETA_APPROVED_TASK_ID=`k171ep964sxabbrgmb21fk9axd87ka1n` at commit `338a7b9e6130ce69dc5fe7f3e2e9ecc4648b4f6a` (Day 79 SHA-pinned).
+**Eta sign-off** : ETA_APPROVED_TASK_ID=`k171ep964sxabbrgmb21fk9axd87ka1n` at commit `338a7b9e6130ce69dc5fe7f3e2e9ecc4648b4f6a` (SHA-pinned).
 **Merge** : PR #545 squash `f509c8d92f0b142bc063a0e9dd070e1993cc729b`.
 
 M3 delivers the session registry and stream-marker protocol that connects the VP MCP server
@@ -56,7 +75,7 @@ Change is surgical — existing return shape is preserved; marker is appended as
 ### Ack checklist
 
 NEW `docs/M3-ACK-CHECKLIST.md` — bilingual FR/EN post-deploy verification checklist
-for Marie + Ismaël. Covers: package install, primitive reads, Shadow DOM scoping,
+for the beta verifier cohort. Covers: package install, primitive reads, Shadow DOM scoping,
 stream marker emit + parse, bilingual spot check, WCAG AA (contrast + role attrs),
 default-OFF guard.
 
@@ -80,7 +99,7 @@ default-OFF guard.
 **Mission instance** : `sigma-vantage-peers-mcp-gui-iframe-embed-v1` (k5730xct6rvrwkvxhy5t5js12d87jwfw).
 **Template VR consumed** : `gui-iframe-embed-v1` v1.0.0 (jx7bzk0x1086tgwgj2zrssk2pn87k1ga).
 
-M1 Foundation (adapted MCP-pure paradigm per Pi arbitrage Day 84) :
+M1 Foundation (adapted MCP-pure paradigm per Pi arbitrage 2026-05-28) :
 - NEW `mcp-server/src/ui-resources/index.ts` : URI parser `ui://vp/v1/<primitive>?<query>` + primitive registry + handler factory.
 - NEW `mcp-server/src/ui-resources/primitives/tasks-table.ts` : M1 MVP primitive returning HTML inline (Shadow DOM scoped CSS) — WCAG AA + bilingual FR+EN.
 - `mcp-server/server-http.ts` : wired `ListResourcesRequestSchema` + `ReadResourceRequestSchema` MCP handlers on the existing McpServer instance.
@@ -102,11 +121,13 @@ Bearer sha256 validation : Already in place since v2.3.4 DCR security fix. `mcp-
 
 Tests : 42 new vitest cases in `src/__tests__/ui-resources-m2-primitives.test.ts` (target was ≥22). Covers : PRIMITIVES registry (6 entries), each of 5 new primitives (empty + populated + FR labels + XSS escape + error fallback = 5 cases each), Zod schema roundtrip (VpToolResultSchema all 6 variants accepted, malformed rejected, individual payload schema validations). 0 regression on M1 17 cases + 194 other MCP tests (253/253 total).
 
-M3 next : Registry json-render + `__VP_TOOL_RESULT__<json>` stream marker + smoke E2E + ack-checklist + PI-SIGNED Convex prod deploy + visual ack Marie/Ismaël.
+M3 next : Registry json-render + `__VP_TOOL_RESULT__<json>` stream marker + smoke E2E + ack-checklist + PI-SIGNED Convex prod deploy + visual ack from beta cohort verifiers.
+
+---
 
 ## v2.3.5 — 2026-05-28
 
-**Critical hotfix** — v2.3.3 (PR #539) shipped the backend filters `createdBy` + `updatedSince` and the Zod schema exports but did NOT wire those params into the 4 list MCP tool args blocks. Pi pull-cycle quickstart `list_tasks createdBy="pi" status="review" fields="lite"` was silently dropping `createdBy` at the MCP boundary and returning all visible tasks. Auto-clamp safeguard (Day 83) also could not trigger because Zod `.default(50)` / `.default(20)` on `limit` overrode the absent-value signal before it reached the backend.
+**Critical hotfix** — v2.3.3 (PR #539) shipped the backend filters `createdBy` + `updatedSince` and the Zod schema exports but did NOT wire those params into the 4 list MCP tool args blocks. Pi pull-cycle quickstart `list_tasks createdBy="pi" status="review" fields="lite"` was silently dropping `createdBy` at the MCP boundary and returning all visible tasks. Auto-clamp safeguard (2026-05-27) also could not trigger because Zod `.default(50)` / `.default(20)` on `limit` overrode the absent-value signal before it reached the backend.
 
 Fixes:
 - `mcp-server/src/tools.ts` : 4 list tools now expose `createdBy` (`list_tasks` + `list_tasks_by_mission` only — `list_missions` + `list_briefing_notes` do not accept it backend-side) and `updatedSince` (all 4).
@@ -114,15 +135,15 @@ Fixes:
 
 Tests : 8 new boundary-forwarding cases (`src/__tests__/list-queries-v2.3.5-wire-createdby-updatedsince.test.ts`) — verify MCP layer actually forwards new params to `convex.query` instead of dropping them. 0 regression on existing suites.
 
-Detection : Vantage-Bridge architecture review Sigma scope Day 84 — direct `grep`/`sed` inspection of `tools.ts` confirmed the gap. Backend already correct since v2.3.3 (`convex/tasks.ts:354-357`).
+Detection : Vantage-Bridge architecture review Sigma scope 2026-05-28 — direct `grep`/`sed` inspection of `tools.ts` confirmed the gap. Backend already correct since v2.3.3 (`convex/tasks.ts:354-357`).
 
-Fix-pattern (Day 84 capitalize) : when adding a new param across backend + MCP wrapper, the test suite MUST cover not only schema validation but also the tool-handler→convex.query forwarding boundary. Schema-only tests passed cleanly in v2.3.3 while the actual feature was broken in prod.
+Fix-pattern (2026-05-28 capitalize) : when adding a new param across backend + MCP wrapper, the test suite MUST cover not only schema validation but also the tool-handler→convex.query forwarding boundary. Schema-only tests passed cleanly in v2.3.3 while the actual feature was broken in prod.
 
 VP task : `k177tsvdxzase5sjy2qm9fdvp187kbwr`. Predecessor v2.3.3 PR #539 (`k1796s5j6jfkvkx0tn5n926ftd87jx9p`).
 
 ## v2.3.4 — 2026-05-28
 
-**Security fix** — DCR (Dynamic Client Registration) self-registration now defaults to tenant-scope only. Master scope requires explicit admin authorization (`ADMIN_DCR_TOKEN` / `BEARER_SECRET_MASTER` env var). Closes beta blocker for Marie/Iris RH onboarding identified in VP Cloud audit Day 84.
+**Security fix** — DCR (Dynamic Client Registration) self-registration now defaults to tenant-scope only. Master scope requires explicit admin authorization (`ADMIN_DCR_TOKEN` / `BEARER_SECRET_MASTER` env var). Closes beta blocker for early-access RH cohort onboarding identified in VP Cloud audit 2026-05-28.
 
 Changes:
 - `convex/oauth.ts`: `registerPublicClient` now explicitly rejects `scopeProfile="master"` with a `ScopeViolation` error. Previously only the HTTP server enforced this; the Convex-layer was bypassable via direct internal call.
@@ -131,11 +152,11 @@ Changes:
 
 Tests: 5 new Convex security tests (`convex/oauth-dcr-security.test.ts`) + 5 new MCP scope enforcement tests (`mcp-server/src/__tests__/dcr-scope-enforcement.test.ts`), 0 regression on existing suites.
 
-VP task: k17218rvqyncs1v6rwj3qdzfsn87jj4n. Beta unblock chain: DCR fix → 5 quick wins onboarding (seed-profiles + marie-iris-rh client + README VP Cloud + runbook + email).
+VP task: k17218rvqyncs1v6rwj3qdzfsn87jj4n. Beta unblock chain: DCR fix → 5 quick wins onboarding (seed-profiles + early-access RH cohort client + README VP Cloud + runbook + email).
 
 ## v2.3.3 — 2026-05-28
 
-**Follow-up to v2.3.2 (Day 84 scope élargi)** — Extend list queries with `createdBy` + `updatedSince` filters + auto-clamp safeguard.
+**Follow-up to v2.3.2 (2026-05-28 scope élargi)** — Extend list queries with `createdBy` + `updatedSince` filters + auto-clamp safeguard.
 
 Backend (Convex) :
 - `tasks.list` + `tasks.listByMission` : + `createdBy` (filter by task creator) + `updatedSince` (Unix ms window) + auto-clamp limit=30 when `fields="full"` and no explicit limit
@@ -157,7 +178,7 @@ VP task: `k1796s5j6jfkvkx0tn5n926ftd87jx9p`. Successor of `k17e09ng1tf217n93z9m4
 
 ## v2.3.2 — 2026-05-28
 
-**Hotfix** — Expose `fields="lite"` + `status` array/aliases in MCP tool schemas (Day 82 sprint gap).
+**Hotfix** — Expose `fields="lite"` + `status` array/aliases in MCP tool schemas (2026-05-26 sprint gap).
 
 Backend support for these params shipped in v2.3.1 but the MCP wrapper Zod schemas never exposed them, so MCP clients couldn't pass them. Fixed for 4 list tools:
 

package/dist/server-http.d.ts

@@ -24,4 +24,17 @@
  *   PORT                  — HTTP port (default 3000)
  *   NODE_ENV              — set to "production" on Railway
  */
-export {};
+import { Hono } from "hono";
+/**
+ * D6 helper — extract client_secret from either the Authorization: Basic header
+ * (RFC 6749 §2.3.1 client_secret_basic) or the form body (client_secret_post).
+ * Returns { clientId, clientSecret } when present, else nulls.
+ *
+ * Basic header format: "Basic base64(client_id:client_secret)".
+ * Per RFC 6749 §2.3.1 the values are form-urlencoded before being colon-joined.
+ */
+export declare function parseBasicAuthSecret(authHeader: string | undefined, body: Record<string, string>): {
+    clientId: string | null;
+    clientSecret: string | null;
+};
+export declare const app: Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;

package/dist/server-http.js

@@ -31,6 +31,7 @@ import { ConvexHttpClient } from "convex/browser";
 import { Hono } from "hono";
 import { cors } from "hono/cors";
 import { bearerAuthMiddleware, internalClient, masterOnlyMiddleware, sha256Base64Url, sha256Hex, } from "./src/auth.js";
+import { timingSafeEqual } from "./src/crypto.js";
 import { registerTools } from "./src/tools.js";
 import { listUiResources, readUiResource } from "./src/ui-resources/index.js";
 let pkg;
@@ -86,6 +87,33 @@ function randomOpaqueToken() {
         .map((b) => b.toString(16).padStart(2, "0"))
         .join("");
 }
+/**
+ * D6 helper — extract client_secret from either the Authorization: Basic header
+ * (RFC 6749 §2.3.1 client_secret_basic) or the form body (client_secret_post).
+ * Returns { clientId, clientSecret } when present, else nulls.
+ *
+ * Basic header format: "Basic base64(client_id:client_secret)".
+ * Per RFC 6749 §2.3.1 the values are form-urlencoded before being colon-joined.
+ */
+export function parseBasicAuthSecret(authHeader, body) {
+    if (authHeader?.toLowerCase().startsWith("basic ")) {
+        try {
+            const decoded = atob(authHeader.slice(6).trim());
+            const idx = decoded.indexOf(":");
+            if (idx > 0) {
+                const id = decodeURIComponent(decoded.slice(0, idx));
+                const secret = decodeURIComponent(decoded.slice(idx + 1));
+                return { clientId: id, clientSecret: secret };
+            }
+        }
+        catch {
+            // fall through to body
+        }
+    }
+    const id = typeof body.client_id === "string" ? body.client_id : null;
+    const secret = typeof body.client_secret === "string" ? body.client_secret : null;
+    return { clientId: id, clientSecret: secret };
+}
 async function loadScopeProfile(profileId) {
     return (await internalClient().query(
     // biome-ignore lint/suspicious/noExplicitAny: Convex string API
@@ -94,7 +122,7 @@ async function loadScopeProfile(profileId) {
 // ─────────────────────────────────────────────────────────────────────────────
 // App
 // ─────────────────────────────────────────────────────────────────────────────
-const app = new Hono();
+export const app = new Hono();
 // CORS — Claude web sends requests from claude.ai origin
 app.use("*", cors({
     origin: "*",
@@ -191,6 +219,17 @@ app.post("/register", async (c) => {
     // obtain master-level access. Non-default profiles are provisioned only
     // via POST /admin/oauth/clients (master-token gated).
     const scopeProfile = DEFAULT_PUBLIC_DCR_PROFILE;
+    // RFC 7591 §2: honour token_endpoint_auth_method if provided, else default
+    // to client_secret_basic (confidential). Only "none" / "client_secret_basic"
+    // / "client_secret_post" are accepted; anything else falls back to default.
+    const requestedAuthMethod = typeof body.token_endpoint_auth_method === "string"
+        ? body.token_endpoint_auth_method
+        : undefined;
+    const tokenEndpointAuthMethod = requestedAuthMethod === "none" ||
+        requestedAuthMethod === "client_secret_basic" ||
+        requestedAuthMethod === "client_secret_post"
+        ? requestedAuthMethod
+        : "client_secret_basic";
     try {
         await internalClient().mutation(
         // biome-ignore lint/suspicious/noExplicitAny: Convex string API
@@ -200,6 +239,7 @@ app.post("/register", async (c) => {
             name: clientName,
             redirectUris,
             scopeProfile,
+            tokenEndpointAuthMethod,
         });
     }
     catch (err) {
@@ -214,7 +254,7 @@ app.post("/register", async (c) => {
         client_secret_expires_at: 0, // never expires
         redirect_uris: redirectUris,
         client_name: clientName,
-        token_endpoint_auth_method: "client_secret_post",
+        token_endpoint_auth_method: tokenEndpointAuthMethod,
         grant_types: ["authorization_code", "refresh_token"],
         response_types: ["code"],
         // SC: standardized on mcp:full — consistent with well-known metadata
@@ -256,6 +296,16 @@ app.get("/authorize", async (c) => {
     if (client.revokedAt !== undefined) {
         return c.json({ error: "invalid_client", error_description: "client revoked" }, 400);
     }
+    // D7 — RFC 6749 §3.1.2.3/§3.1.2.4: redirect_uri MUST exact-match a
+    // registered URI. Defense against open-redirect / token-exfiltration via
+    // attacker-controlled redirect. No partial / prefix / wildcard match.
+    const registeredUris = client.redirectUris ?? [];
+    if (registeredUris.length === 0 || !registeredUris.includes(redirectUri)) {
+        return c.json({
+            error: "invalid_request",
+            error_description: "redirect_uri does not match a registered redirect URI for this client",
+        }, 400);
+    }
     const masterTokenForAuthCode = process.env.BEARER_SECRET_MASTER;
     if (!masterTokenForAuthCode) {
         console.error("[oauth] BEARER_SECRET_MASTER not set — cannot mint authorization code");
@@ -344,6 +394,29 @@ app.post("/token", async (c) => {
         if (!client || client.revokedAt !== undefined) {
             return c.json({ error: "invalid_client" }, 400);
         }
+        // D6 — RFC 6749 §4.1.3 + §6: confidential clients MUST authenticate at
+        // /token. Default (absent) treated as confidential for backward compat.
+        // Public clients (token_endpoint_auth_method="none") skip the check —
+        // PKCE provides the binding (already verified above).
+        const authMethod = client.tokenEndpointAuthMethod ?? "client_secret_basic";
+        if (authMethod !== "none") {
+            const { clientSecret } = parseBasicAuthSecret(c.req.header("authorization"), body);
+            if (!clientSecret) {
+                c.header("WWW-Authenticate", 'Basic realm="oauth"');
+                return c.json({
+                    error: "invalid_client",
+                    error_description: "client authentication required for confidential client",
+                }, 401);
+            }
+            const presentedHash = await sha256Hex(clientSecret);
+            if (!client.clientSecretHash ||
+                !(await timingSafeEqual(presentedHash, client.clientSecretHash))) {
+                return c.json({
+                    error: "invalid_client",
+                    error_description: "client_secret mismatch",
+                }, 401);
+            }
+        }
         const profile = await loadScopeProfile(client.scopeProfile);
         if (!profile) {
             console.error("[oauth] scope_profile not found during token issue:", client.scopeProfile);
@@ -406,6 +479,32 @@ app.post("/token", async (c) => {
         if (!record) {
             return c.json({ error: "invalid_grant" }, 400);
         }
+        // D6 — confidential client authentication on refresh too (RFC 6749 §6).
+        const refreshClient = (await internalClient().query(
+        // biome-ignore lint/suspicious/noExplicitAny: Convex string API
+        "oauth:getClientByClientId", { clientId: record.clientId }));
+        if (!refreshClient || refreshClient.revokedAt !== undefined) {
+            return c.json({ error: "invalid_client" }, 400);
+        }
+        const refreshAuthMethod = refreshClient.tokenEndpointAuthMethod ?? "client_secret_basic";
+        if (refreshAuthMethod !== "none") {
+            const { clientSecret } = parseBasicAuthSecret(c.req.header("authorization"), body);
+            if (!clientSecret) {
+                c.header("WWW-Authenticate", 'Basic realm="oauth"');
+                return c.json({
+                    error: "invalid_client",
+                    error_description: "client authentication required for confidential client",
+                }, 401);
+            }
+            const presentedHash = await sha256Hex(clientSecret);
+            if (!refreshClient.clientSecretHash ||
+                !(await timingSafeEqual(presentedHash, refreshClient.clientSecretHash))) {
+                return c.json({
+                    error: "invalid_client",
+                    error_description: "client_secret mismatch",
+                }, 401);
+            }
+        }
         const profile = await loadScopeProfile(record.scopeProfile);
         if (!profile) {
             return c.json({ error: "server_error" }, 500);
@@ -480,6 +579,14 @@ admin.post("/oauth/clients", async (c) => {
     const redirectUris = Array.isArray(body.redirect_uris)
         ? body.redirect_uris
         : [];
+    const adminRequestedAuthMethod = typeof body.token_endpoint_auth_method === "string"
+        ? body.token_endpoint_auth_method
+        : undefined;
+    const adminTokenEndpointAuthMethod = adminRequestedAuthMethod === "none" ||
+        adminRequestedAuthMethod === "client_secret_basic" ||
+        adminRequestedAuthMethod === "client_secret_post"
+        ? adminRequestedAuthMethod
+        : "client_secret_basic";
     if (!name || !scopeProfile) {
         return c.json({
             error: "invalid_request",
@@ -503,6 +610,7 @@ admin.post("/oauth/clients", async (c) => {
             name,
             redirectUris,
             scopeProfile,
+            tokenEndpointAuthMethod: adminTokenEndpointAuthMethod,
         });
     }
     catch (err) {
@@ -578,16 +686,7 @@ app.all("/mcp", bearerAuthMiddleware(), async (c) => {
             // biome-ignore lint/suspicious/noExplicitAny: Convex string API
             return convex.query(functionName, args);
         };
-        const resource = await readUiResource(uri.toString(), fetchConvex);
-        return {
-            contents: [
-                {
-                    uri: resource.uri,
-                    mimeType: resource.mimeType,
-                    text: resource.text,
-                },
-            ],
-        };
+        return await readUiResource(uri.toString(), fetchConvex);
     });
     const transport = new WebStandardStreamableHTTPServerTransport();
     await server.connect(transport);
@@ -598,14 +697,18 @@ app.all("/mcp", bearerAuthMiddleware(), async (c) => {
 // ─────────────────────────────────────────────────────────────────────────────
 const PORT = Number(process.env.PORT ?? 3000);
 const HOSTNAME = "0.0.0.0";
-// Explicit Bun.serve() — does not rely on default-export auto-detection,
-// which can fail when started via `bun run <file>` (vs `bun <file>`).
-// @ts-expect-error — Bun global available at runtime on Railway
-const server = Bun.serve({
-    port: PORT,
-    hostname: HOSTNAME,
-    fetch: app.fetch,
-});
-console.log(`[vantage-peers-mcp] HTTP transport listening on ${server.hostname}:${server.port}`);
-console.log(`[vantage-peers-mcp] Health: http://${server.hostname}:${server.port}/health`);
-console.log(`[vantage-peers-mcp] MCP:    http://${server.hostname}:${server.port}/mcp`);
+// Bootstrap is gated so tests can `import { app }` without binding a socket.
+// VP_TEST_MODE=1 short-circuits the listener (vitest sets this in setup).
+if (process.env.VP_TEST_MODE !== "1") {
+    // Explicit Bun.serve() — does not rely on default-export auto-detection,
+    // which can fail when started via `bun run <file>` (vs `bun <file>`).
+    // @ts-expect-error — Bun global available at runtime on Railway
+    const server = Bun.serve({
+        port: PORT,
+        hostname: HOSTNAME,
+        fetch: app.fetch,
+    });
+    console.log(`[vantage-peers-mcp] HTTP transport listening on ${server.hostname}:${server.port}`);
+    console.log(`[vantage-peers-mcp] Health: http://${server.hostname}:${server.port}/health`);
+    console.log(`[vantage-peers-mcp] MCP:    http://${server.hostname}:${server.port}/mcp`);
+}

package/dist/src/crypto.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Constant-time comparison helper for hex-encoded hash strings.
+ *
+ * Ported from `convex/oauth.ts:23-45` (Day 47 master-token gate) to close
+ * Eta F1 MAJOR on PR #621 (S1.5 D6+D7): the `presentedHash !== client.clientSecretHash`
+ * checks at `mcp-server/server-http.ts` L577-580 (authorization_code grant) and
+ * L692 (refresh_token grant) were non-constant-time, leaking a timing oracle on
+ * confidential client authentication (RFC 6749 §6).
+ *
+ * Algorithm is **identical** to the Convex helper:
+ *   1. TextEncoder → bytes.
+ *   2. Length mismatch → still run a dummy HMAC over equal-length input to
+ *      avoid a branch-timing leak, then return false.
+ *   3. Equal length → XOR-accumulate diff, return diff === 0.
+ *
+ * Web Crypto (`crypto.subtle`) is used (not the Node `crypto.timingSafeEqual`
+ * variant) for two reasons:
+ *   - Parity with the Convex implementation — same algorithm, same surface.
+ *   - sha256Hex outputs are 64-char hex strings so length is normally equal,
+ *     but defensively we handle mismatch (e.g. empty string fallback when
+ *     `clientSecretHash` is undefined on a malformed row).
+ */
+export declare function timingSafeEqual(a: string, b: string): Promise<boolean>;

package/dist/src/crypto.js

@@ -0,0 +1,39 @@
+/**
+ * Constant-time comparison helper for hex-encoded hash strings.
+ *
+ * Ported from `convex/oauth.ts:23-45` (Day 47 master-token gate) to close
+ * Eta F1 MAJOR on PR #621 (S1.5 D6+D7): the `presentedHash !== client.clientSecretHash`
+ * checks at `mcp-server/server-http.ts` L577-580 (authorization_code grant) and
+ * L692 (refresh_token grant) were non-constant-time, leaking a timing oracle on
+ * confidential client authentication (RFC 6749 §6).
+ *
+ * Algorithm is **identical** to the Convex helper:
+ *   1. TextEncoder → bytes.
+ *   2. Length mismatch → still run a dummy HMAC over equal-length input to
+ *      avoid a branch-timing leak, then return false.
+ *   3. Equal length → XOR-accumulate diff, return diff === 0.
+ *
+ * Web Crypto (`crypto.subtle`) is used (not the Node `crypto.timingSafeEqual`
+ * variant) for two reasons:
+ *   - Parity with the Convex implementation — same algorithm, same surface.
+ *   - sha256Hex outputs are 64-char hex strings so length is normally equal,
+ *     but defensively we handle mismatch (e.g. empty string fallback when
+ *     `clientSecretHash` is undefined on a malformed row).
+ */
+export async function timingSafeEqual(a, b) {
+    const encoder = new TextEncoder();
+    const aBytes = encoder.encode(a);
+    const bBytes = encoder.encode(b);
+    if (aBytes.length !== bBytes.length) {
+        // Still do a comparison on equal-length buffers to avoid branch-timing leak.
+        const dummy = new Uint8Array(aBytes.length);
+        const aKey = await crypto.subtle.importKey("raw", aBytes.length > 0 ? aBytes : new Uint8Array([0]), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+        await crypto.subtle.sign("HMAC", aKey, dummy);
+        return false;
+    }
+    let diff = 0;
+    for (let i = 0; i < aBytes.length; i++) {
+        diff |= aBytes[i] ^ bBytes[i];
+    }
+    return diff === 0;
+}

package/dist/src/scope-filter.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Sprint S3.1 B2 — scope-aware filter helpers for VP MCP tools.
+ *
+ * Replaces the binary `guardMasterOnly` 403 rejection with row-level filtering
+ * so non-master scoped OAuth clients (Marie's onboarding case 2026-06-01) can
+ * see their own data instead of receiving a blanket Forbidden.
+ *
+ * Doctrine references:
+ *   - decisions/doctrine-scope-aware-filter-2026-05-26.md (D3 base)
+ *   - memory j579y6f31g7xzgtgdnpgetdmjx87ztyj (D9-D14 extension)
+ *
+ * Contract:
+ *   - Master scope (isMasterScope === true) = wildcard pass.
+ *   - Legacy bearer (oauthCtx === undefined) = wildcard pass (treated as master-
+ *     equivalent for backward-compatibility with mcpTenants Pi/Tau/Phi paths).
+ *   - Non-master scope = row passes iff:
+ *       row.createdBy ∈ oauthCtx.fromAllowList
+ *       OR
+ *       row.namespace startsWith one of oauthCtx.namespaceReadPrefixes
+ *           (prefix matched as exact-equal OR followed by '/' boundary)
+ *   - Row missing BOTH `createdBy` and `namespace` = denied for non-master.
+ *
+ * NOTE: this module is intentionally framework-agnostic — no McpServer / Hono
+ * imports — to keep the helpers trivially unit-testable.
+ */
+import { type OAuthContext } from "./auth.js";
+/**
+ * Row shape accepted by the scope filter. All fields optional because real
+ * Convex documents from list_peers / list_messages / etc. don't all carry both.
+ */
+export type ScopeFilterable = {
+    createdBy?: string;
+    namespace?: string;
+};
+/**
+ * Core predicate. Returns true when the row is visible to the caller.
+ *
+ *   - Master scope (isMasterScope === true)            → true (wildcard)
+ *   - Legacy bearer (oauthCtx === undefined)           → true (back-compat)
+ *   - row.createdBy ∈ oauthCtx.fromAllowList           → true
+ *   - row.namespace === prefix OR startsWith prefix+'/'
+ *     for any prefix ∈ oauthCtx.namespaceReadPrefixes  → true
+ *   - otherwise                                        → false
+ *
+ * Substring matches that don't fall on a '/' boundary are explicitly rejected
+ * (e.g. namespace="orchestrator/alphabet" does NOT match prefix
+ * "orchestrator/alpha"). This avoids the classic prefix-isolation bypass.
+ */
+export declare function passesScopeFilter(oauthCtx: OAuthContext | undefined, row: ScopeFilterable): boolean;
+/**
+ * Filter a list of rows (post-query). Used by list_* tools.
+ */
+export declare function scopeFilterList<T extends ScopeFilterable>(oauthCtx: OAuthContext | undefined, rows: T[]): T[];
+/**
+ * Assert a single row passes (get_* tools). Returns the row when allowed, null
+ * otherwise — callers translate null to a 404-equivalent "not found" MCP error
+ * to avoid leaking the difference between "absent" and "filtered out".
+ */
+export declare function scopeFilterGet<T extends ScopeFilterable>(oauthCtx: OAuthContext | undefined, row: T | null | undefined): T | null;
+/**
+ * Helper for callers that want a single "is master / legacy" predicate without
+ * importing isMasterScope directly. Mirrors the legacy-bearer-passes-through
+ * convention.
+ */
+export declare function isWildcardScope(ctx: OAuthContext | undefined): boolean;

package/dist/src/scope-filter.js

@@ -0,0 +1,84 @@
+/**
+ * Sprint S3.1 B2 — scope-aware filter helpers for VP MCP tools.
+ *
+ * Replaces the binary `guardMasterOnly` 403 rejection with row-level filtering
+ * so non-master scoped OAuth clients (Marie's onboarding case 2026-06-01) can
+ * see their own data instead of receiving a blanket Forbidden.
+ *
+ * Doctrine references:
+ *   - decisions/doctrine-scope-aware-filter-2026-05-26.md (D3 base)
+ *   - memory j579y6f31g7xzgtgdnpgetdmjx87ztyj (D9-D14 extension)
+ *
+ * Contract:
+ *   - Master scope (isMasterScope === true) = wildcard pass.
+ *   - Legacy bearer (oauthCtx === undefined) = wildcard pass (treated as master-
+ *     equivalent for backward-compatibility with mcpTenants Pi/Tau/Phi paths).
+ *   - Non-master scope = row passes iff:
+ *       row.createdBy ∈ oauthCtx.fromAllowList
+ *       OR
+ *       row.namespace startsWith one of oauthCtx.namespaceReadPrefixes
+ *           (prefix matched as exact-equal OR followed by '/' boundary)
+ *   - Row missing BOTH `createdBy` and `namespace` = denied for non-master.
+ *
+ * NOTE: this module is intentionally framework-agnostic — no McpServer / Hono
+ * imports — to keep the helpers trivially unit-testable.
+ */
+import { isMasterScope } from "./auth.js";
+/**
+ * Core predicate. Returns true when the row is visible to the caller.
+ *
+ *   - Master scope (isMasterScope === true)            → true (wildcard)
+ *   - Legacy bearer (oauthCtx === undefined)           → true (back-compat)
+ *   - row.createdBy ∈ oauthCtx.fromAllowList           → true
+ *   - row.namespace === prefix OR startsWith prefix+'/'
+ *     for any prefix ∈ oauthCtx.namespaceReadPrefixes  → true
+ *   - otherwise                                        → false
+ *
+ * Substring matches that don't fall on a '/' boundary are explicitly rejected
+ * (e.g. namespace="orchestrator/alphabet" does NOT match prefix
+ * "orchestrator/alpha"). This avoids the classic prefix-isolation bypass.
+ */
+export function passesScopeFilter(oauthCtx, row) {
+    if (!oauthCtx)
+        return true;
+    if (isMasterScope(oauthCtx))
+        return true;
+    const { createdBy, namespace } = row;
+    if (createdBy && oauthCtx.fromAllowList.includes(createdBy))
+        return true;
+    if (namespace) {
+        for (const p of oauthCtx.namespaceReadPrefixes) {
+            if (namespace === p)
+                return true;
+            if (namespace.startsWith(`${p}/`))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Filter a list of rows (post-query). Used by list_* tools.
+ */
+export function scopeFilterList(oauthCtx, rows) {
+    return rows.filter((r) => passesScopeFilter(oauthCtx, r));
+}
+/**
+ * Assert a single row passes (get_* tools). Returns the row when allowed, null
+ * otherwise — callers translate null to a 404-equivalent "not found" MCP error
+ * to avoid leaking the difference between "absent" and "filtered out".
+ */
+export function scopeFilterGet(oauthCtx, row) {
+    if (row == null)
+        return null;
+    return passesScopeFilter(oauthCtx, row) ? row : null;
+}
+/**
+ * Helper for callers that want a single "is master / legacy" predicate without
+ * importing isMasterScope directly. Mirrors the legacy-bearer-passes-through
+ * convention.
+ */
+export function isWildcardScope(ctx) {
+    if (!ctx)
+        return true;
+    return isMasterScope(ctx);
+}

package/dist/src/tools.js

@@ -10,6 +10,7 @@
 import { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 import { checkFromAllowed, checkNamespaceRead, checkNamespaceWrite, isMasterScope, } from "./auth.js";
+import { scopeFilterGet, scopeFilterList } from "./scope-filter.js";
 import { wrapToolResult } from "./ui-resources/stream-marker.js";
 // ─────────────────────────────────────────────────────────────────────────────
 // VP_EMIT_UI_MARKERS gate
@@ -582,14 +583,18 @@ export function registerTools(server, convex, oauthCtx) {
         title: "Get memory",
     }, async ({ memoryId }) => {
         try {
-            const _scopeDenied = guardMasterOnly("get_memory");
-            if (_scopeDenied)
-                return _scopeDenied;
+            // S3.1.A Wave A — scope-aware filter replaces guardMasterOnly.
+            // Non-master clients may now read their own data; cross-tenant rows
+            // collapse to a non-leaky "not found" shape (same as a missing row).
             const memory = await convex.query("memories:getMemory", {
                 memoryId,
             });
+            const filtered = scopeFilterGet(oauthCtx, memory);
+            if (filtered === null) {
+                return mcpError(`Memory not found: ${memoryId}`);
+            }
             return {
-                content: [{ type: "text", text: JSON.stringify(memory, null, 2) }],
+                content: [{ type: "text", text: JSON.stringify(filtered, null, 2) }],
             };
         }
         catch (error) {
@@ -937,10 +942,20 @@ export function registerTools(server, convex, oauthCtx) {
                 : Array.isArray(memories?.page)
                     ? memories.page
                     : [];
-            const baseText = capListResponseBytes(memories, JSON.stringify(memories, null, 2), "list_memories");
+            // S3.1.A Wave A — row-level scope filter on the post-query list.
+            // Master + legacy bearer pass through unchanged. Non-master clients
+            // see only rows whose createdBy ∈ fromAllowList OR whose namespace
+            // matches one of namespaceReadPrefixes (exact or '/' boundary).
+            const filteredList = scopeFilterList(oauthCtx, rawList);
+            // Preserve the original response shape (array vs {page} envelope)
+            // so downstream consumers don't need to special-case Wave A.
+            const filteredEnvelope = Array.isArray(memories)
+                ? filteredList
+                : { ...memories, page: filteredList };
+            const baseText = capListResponseBytes(filteredEnvelope, JSON.stringify(filteredEnvelope, null, 2), "list_memories");
             const text = appendMarkerIfEnabled(baseText, () => ({
                 kind: "memory-quote",
-                items: rawList.map((m) => ({
+                items: filteredList.map((m) => ({
                     _id: m._id,
                     namespace: m.namespace,
                     type: m.type,

package/dist/src/ui-resources/index.d.ts

@@ -1,20 +1,27 @@
 /**
  * SEP-1865 ui:// resources for VantagePeers Generative UI.
  *
+ * Canonical PR #1865 (MERGED 2026-01-28) compliance:
+ *  - MIME: text/html;profile=mcp-app (RESOURCE_MIME_TYPE)
+ *  - _meta.ui: UIResourceMeta envelope (nested, NOT flat _meta["ui/resourceUri"])
+ *  - Capability key declared at server initialize: io.modelcontextprotocol/ui
+ *  - Fallback markdown content item in resources/read response (Critical Rule #1)
+ *
+ * Uses @mcp-ui/server createUIResource() helper (reference impl by SEP-1865 co-author).
+ *
  * URI pattern : ui://vp/v1/<primitive>?<query>
  * Examples :
  *   ui://vp/v1/tasks-table?assignedTo=pi&status=review&fields=lite&limit=10
  *   ui://vp/v1/messages-feed?recipient=sigma&limit=20
  *
- * M1 scope : 1 primitive (tasks-table) — proves the pipeline.
- * M2 scope : ≥6 primitives (tasks/messages/diary/missions/briefingNotes/memories).
- *
  * Pattern Hybrid 60% static lit-ui + 11% Gen UI + 27% Hybrid (cf vp-gui-views-research-2026-05-28.md).
- * Returns HTML inline with embedded JS + CSS Shadow DOM scoped.
  *
  * Reference instance Theta : theta-vantage-crm-gui-iframe-embed-v1 (blissful-gopher-531).
  * Mission Sigma : sigma-vantage-peers-mcp-gui-iframe-embed-v1 (k5730xct6rvrwkvxhy5t5js12d87jwfw).
  */
+export declare const MCP_UI_CAPABILITY_KEY: "io.modelcontextprotocol/ui";
+export declare const MCP_UI_MIME_TYPE = "text/html;profile=mcp-app";
+type UIResourceMeta = Record<string, never>;
 export type UiResourceParsed = {
     primitive: string;
     query: URLSearchParams;
@@ -23,14 +30,30 @@ export declare function parseUiUri(uri: string): UiResourceParsed | null;
 export declare const PRIMITIVES: readonly ["tasks-table", "messages-feed", "diary-entry", "mission-timeline", "briefing-note", "memory-quote"];
 export type Primitive = (typeof PRIMITIVES)[number];
 export declare const PRIMITIVE_DESCRIPTIONS: Record<Primitive, string>;
-export declare function listUiResources(): Array<{
+export type UiResourceListEntry = {
     uri: string;
     name: string;
     description: string;
     mimeType: string;
-}>;
-export declare function readUiResource(uri: string, fetchConvex: (functionName: string, args: Record<string, unknown>) => Promise<unknown>): Promise<{
+    _meta: {
+        ui: UIResourceMeta;
+    };
+};
+export declare function listUiResources(): UiResourceListEntry[];
+export type UiResourceContent = {
     uri: string;
     mimeType: string;
     text: string;
-}>;
+    _meta?: {
+        ui: UIResourceMeta;
+    };
+} | {
+    uri: string;
+    mimeType: "text/markdown";
+    text: string;
+};
+export type UiResourceReadResult = {
+    contents: UiResourceContent[];
+};
+export declare function readUiResource(uri: string, fetchConvex: (functionName: string, args: Record<string, unknown>) => Promise<unknown>): Promise<UiResourceReadResult>;
+export {};

package/dist/src/ui-resources/index.js

@@ -1,26 +1,37 @@
 /**
  * SEP-1865 ui:// resources for VantagePeers Generative UI.
  *
+ * Canonical PR #1865 (MERGED 2026-01-28) compliance:
+ *  - MIME: text/html;profile=mcp-app (RESOURCE_MIME_TYPE)
+ *  - _meta.ui: UIResourceMeta envelope (nested, NOT flat _meta["ui/resourceUri"])
+ *  - Capability key declared at server initialize: io.modelcontextprotocol/ui
+ *  - Fallback markdown content item in resources/read response (Critical Rule #1)
+ *
+ * Uses @mcp-ui/server createUIResource() helper (reference impl by SEP-1865 co-author).
+ *
  * URI pattern : ui://vp/v1/<primitive>?<query>
  * Examples :
  *   ui://vp/v1/tasks-table?assignedTo=pi&status=review&fields=lite&limit=10
  *   ui://vp/v1/messages-feed?recipient=sigma&limit=20
  *
- * M1 scope : 1 primitive (tasks-table) — proves the pipeline.
- * M2 scope : ≥6 primitives (tasks/messages/diary/missions/briefingNotes/memories).
- *
  * Pattern Hybrid 60% static lit-ui + 11% Gen UI + 27% Hybrid (cf vp-gui-views-research-2026-05-28.md).
- * Returns HTML inline with embedded JS + CSS Shadow DOM scoped.
  *
  * Reference instance Theta : theta-vantage-crm-gui-iframe-embed-v1 (blissful-gopher-531).
  * Mission Sigma : sigma-vantage-peers-mcp-gui-iframe-embed-v1 (k5730xct6rvrwkvxhy5t5js12d87jwfw).
  */
+import { RESOURCE_MIME_TYPE } from "@mcp-ui/server";
 import { renderBriefingNote } from "./primitives/briefing-note.js";
 import { renderDiaryEntry } from "./primitives/diary-entry.js";
 import { renderMemoryQuote } from "./primitives/memory-quote.js";
 import { renderMessagesFeed } from "./primitives/messages-feed.js";
 import { renderMissionTimeline } from "./primitives/mission-timeline.js";
 import { renderTasksTable } from "./primitives/tasks-table.js";
+// MCP Apps capability negotiation key (declared at server initialize handshake).
+// Tools opting into UI resources reference it from their _meta.ui field.
+export const MCP_UI_CAPABILITY_KEY = "io.modelcontextprotocol/ui";
+// PR #1865 MIME — re-export from @mcp-ui/server for downstream visibility.
+export const MCP_UI_MIME_TYPE = RESOURCE_MIME_TYPE;
+const DEFAULT_UI_META = {};
 // URI parser : ui://vp/v1/<primitive>?<query>
 const UI_URI_RE = /^ui:\/\/vp\/v1\/([a-z][a-z0-9-]*)(?:\?(.*))?$/;
 export function parseUiUri(uri) {
@@ -51,16 +62,36 @@ export const PRIMITIVE_DESCRIPTIONS = {
     "briefing-note": "Render briefing note details. Query params: noteId or (topic + limit), lang.",
     "memory-quote": "Render memory quotes from a namespace. Query params: namespace, type, limit, lang.",
 };
-// Resource list — returned by resources/list MCP handler
+// Resource list — returned by resources/list MCP handler.
+// PR #1865 canonical: mimeType=text/html;profile=mcp-app + _meta.ui envelope.
 export function listUiResources() {
     return PRIMITIVES.map((p) => ({
         uri: `ui://vp/v1/${p}`,
         name: p,
         description: PRIMITIVE_DESCRIPTIONS[p],
-        mimeType: "text/html",
+        mimeType: MCP_UI_MIME_TYPE,
+        _meta: { ui: DEFAULT_UI_META },
     }));
 }
-// Resource read — dispatched by primitive name. Returns HTML inline.
+// Markdown fallback per Critical Rule #1: every UI resource MUST provide a
+// meaningful text-only payload for hosts without the UI extension. We render a
+// short hint + the primitive description so model + non-UI clients still get
+// usable output (raw HTML is not a substitute — it is the same content the iframe
+// would render, defeating the fallback purpose).
+function renderMarkdownFallback(uri, primitive) {
+    const desc = PRIMITIVE_DESCRIPTIONS[primitive];
+    return [
+        `# ${primitive}`,
+        "",
+        `This resource (${uri}) provides an interactive UI rendering for VantagePeers \`${primitive}\` data.`,
+        "",
+        desc,
+        "",
+        "Your client does not appear to support the MCP UI extension (`text/html;profile=mcp-app`). For a textual view of the same data, call the corresponding VantagePeers tool directly (e.g. `list_tasks`, `list_messages`, `list_diaries`, `list_missions`, `list_briefing_notes`, `recall`) with equivalent filters.",
+    ].join("\n");
+}
+// Resource read — dispatched by primitive name. Returns canonical
+// resources/read contents array: [HTML profile=mcp-app, markdown fallback].
 export async function readUiResource(uri, fetchConvex) {
     const parsed = parseUiUri(uri);
     if (!parsed) {
@@ -69,8 +100,9 @@ export async function readUiResource(uri, fetchConvex) {
     if (!PRIMITIVES.includes(parsed.primitive)) {
         throw new Error(`[VP UI Resources] Unknown primitive: ${parsed.primitive}. Available: ${PRIMITIVES.join(", ")}`);
     }
+    const primitive = parsed.primitive;
     let html;
-    switch (parsed.primitive) {
+    switch (primitive) {
         case "tasks-table":
             html = await renderTasksTable(parsed.query, fetchConvex);
             break;
@@ -93,8 +125,18 @@ export async function readUiResource(uri, fetchConvex) {
             throw new Error(`[VP UI Resources] Unimplemented primitive: ${parsed.primitive}`);
     }
     return {
-        uri,
-        mimeType: "text/html",
-        text: html,
+        contents: [
+            {
+                uri,
+                mimeType: MCP_UI_MIME_TYPE,
+                text: html,
+                _meta: { ui: DEFAULT_UI_META },
+            },
+            {
+                uri,
+                mimeType: "text/markdown",
+                text: renderMarkdownFallback(uri, primitive),
+            },
+        ],
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vantage-peers-mcp",
-  "version": "2.4.12",
+  "version": "2.4.14",
   "description": "MCP server for VantagePeers — shared memory, messaging, and task coordination for AI agent teams",
   "type": "module",
   "main": "./dist/server.js",
@@ -25,7 +25,10 @@
     "prepublishOnly": "npm run build",
     "dev": "bun run server.ts",
     "start": "bun run dist/server-http.js",
-    "dev:http": "bun run server-http.ts"
+    "dev:http": "bun run server-http.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
   },
   "repository": {
     "type": "git",
@@ -54,11 +57,18 @@
     "rag",
     "vector-search"
   ],
-  "author": "ElPi Corp",
+  "author": "VantageOS AI Orchestrator Team",
+  "contributors": [
+    "Pi (π) — Lead orchestrator",
+    "Laurent Perello — Founder, supervisor",
+    "ElPi Corp"
+  ],
   "license": "FSL-1.1-Apache-2.0",
   "dependencies": {
+    "@mcp-ui/server": "^6.1.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "convex": "^1.34.0",
+    "@vantageos/mosaic": "^0.1.2",
+    "convex": ">=1.0.0",
     "dotenv": "^17.4.2",
     "zod": "^4.3.6"
   },
@@ -66,14 +76,16 @@
     "convex": ">=1.0.0"
   },
   "devDependencies": {
+    "@types/node": "^24.12.2",
+    "@vitest/coverage-v8": "^4.1.8",
     "typescript": "^5.9.3",
-    "@types/node": "^24.12.2"
+    "vitest": "^4.1.8"
   },
   "overrides": {
     "path-to-regexp": "^8.4.0"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "publishConfig": {
     "access": "public",