vantage-peers-mcp 2.4.14 → 2.5.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## [2.5.0] — 2026-06-06 — Day 92 VP MCP quality overhaul (mission k57a36y8)
+
+Day 92 mission `k57a36y8w5t085bqr23dsmvb2d882506` ships a fleet-wide VP MCP quality bump
+across audit, docs, hooks, security, and consistency dimensions. 15 PRs merged to main.
+
+### Phase A — Audit + new tools
+- **A1** Day 92 VP MCP tools audit matrix (85 tools, 14 P0 zero-auth gaps) — `docs/test-reports/day92-vp-mcp-audit-matrix.md`.
+- **A2** Consistency analysis report — `docs/test-reports/day92-vp-mcp-consistency-analysis.md`.
+- **A3** New `whoami` LECTURE tool — first per-tool `outputSchema` export precedent.
+- **A4** Consolidated gap matrix — `docs/test-reports/day92-vp-mcp-gap-matrix-consolidated.md`.
+
+### Phase B — Documentation
+- **B1** `docs/cloud/security-multi-tenant.md` §4 scope-aware filter framework rewrite.
+- **B2** `docs/cloud/tools-quality-standard.md` (NEW) — 12-section bilingual quality standard.
+- **B3** `docs/cloud/onboarding-customer.md` (NEW) — customer onboarding guide (bilingual FR+EN).
+
+### Phase C — Consistency
+- **C0** 14 P0 zero-auth write tools secured with `guardMasterOnly` (C0.1 → C0.6, 6 PRs).
+- **C1** 87 Zod `outputSchema` exports per per-family envelope standard (B2 §3).
+- **C2** Orchestrator-id NFC normalization + case-insensitive matching; idempotent prod migration `convex/migrations/c2-normalize-orchestrator-ids.ts` (7 tables).
+- **C3** 97 tool descriptions standardized + 10 canonical aliases gated through `guardMasterOnly` (security regression fixed in iter 2) + alias-c0-gate-coverage test (15/15 PASS).
+- **C4** Legacy `claude-peers` references removed repo-wide + `grep-gate` CI workflow.
+
+### Phase F — Hooks + plugin
+- **F1** New consolidated `validate_task_payload` MCP tool + TypeScript validator library (replaces 5 single-axis hooks).
+- **F2** Plugin propagation runbook + `plugin-vs-workspace-hooks.md` doctrine.
+
+### Scope-aware filtering
+- `list_tasks` `fromAllowList[]` + case-insensitive matching (PR #654, #661).
+- 3 admin endpoints reinstated for Marie cohort (prior session).
+
+### Tenant trio
+- Persistent test tenant trio (alpha/beta/gamma) seeded on prod with bearers, scope_profiles, and seed data for cross-orchestrator E2E.
+
+### Deploy authorization
+- `PI_AUTHORIZED_TASK_ID=k1751nfs27t9f9mpvg3ppd6xad884r59` (Day 82 doctrine).
+- Mission: `k57a36y8w5t085bqr23dsmvb2d882506`.
+- Branch: `release/v2.5.0` opened against `main` at HEAD `18a5530`.
+
 ## [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.

package/README.md

@@ -3,11 +3,11 @@
 [![npm version](https://img.shields.io/npm/v/vantage-peers-mcp)](https://www.npmjs.com/package/vantage-peers-mcp)
 [![npm downloads](https://img.shields.io/npm/dm/vantage-peers-mcp)](https://www.npmjs.com/package/vantage-peers-mcp)
 [![License: FSL-1.1-Apache-2.0](https://img.shields.io/badge/license-FSL--1.1--Apache--2.0-blue)](https://github.com/vantageos-agency/vantage-peers/blob/main/LICENSE)
-[![Tests: 84/84](https://img.shields.io/badge/MCP_tools-84_registered-green)]()
+[![Tests: 97/97](https://img.shields.io/badge/MCP_tools-97_registered-green)]()
 
 MCP server for [VantagePeers](https://vantagepeers.com) — shared memory, messaging, and task coordination for AI agent teams.
 
-84 tools across 18 categories: memory, profiles, tasks, missions, mission templates, messages, diary, briefing notes, search (RAG), issues, fix patterns, error monitoring, deployments, business units, components, mandates, recurring tasks, and session. All tools ship with ChatGPT Apps SDK annotations (`readOnlyHint`, `openWorldHint`, `destructiveHint`) for native UX in ChatGPT custom connectors.
+97 tools across 18 categories: memory, profiles, tasks, missions, mission templates, messages, diary, briefing notes, search (RAG), issues, fix patterns, error monitoring, deployments, business units, components, mandates, recurring tasks, and session. All tools ship with ChatGPT Apps SDK annotations (`readOnlyHint`, `openWorldHint`, `destructiveHint`) for native UX in ChatGPT custom connectors.
 
 ## Quick start
 
@@ -17,6 +17,20 @@ npx vantage-peers-mcp
 
 Requires `CONVEX_URL` pointing to your VantagePeers Convex deployment.
 
+## What's new in v2.5.0
+
+Day 92 VP MCP quality overhaul (mission `k57a36y8w5t085bqr23dsmvb2d882506`, PR #678):
+
+- **C0 — 14 P0 zero-auth write tools secured** with master-only gates (`guardMasterOnly` / `checkFromAllowed`); all 14 tools identified in the A1 audit matrix (commit `d03d2d7`) now require an explicit scope gate before any mutation reaches Convex.
+- **C1 — 87 Zod `outputSchema` exports** following the per-family envelope standard (`create_*` → `{id,...}`, `list_*` → `{items,cursor}`, `delete_*` → `{id,deleted:true}`, etc.) based on the `whoamiOutputSchema` precedent (commit `5231811`).
+- **C2 — Unicode NFC normalization + case-insensitive orchestrator-ID matching** applied at all write paths and filter comparisons; closes the NFD/NFC silent mismatch class discovered in the Hélios/helios production regression.
+- **C3 — 97 tool descriptions standardized** (1-line summary + WHEN clause + concrete EXAMPLE, 80–500 chars) + 10 canonical aliases aligned to the `verb_noun_snake` whitelist.
+- **C4 — `claude-peers` legacy references removed** from source and docs + grep-gate CI check to prevent reintroduction.
+- **A3 — `whoami` LECTURE tool** (PR #661, commit `5231811`) — returns `suggested_orchestrator_id`, `scope_profile`, and `namespace_read_prefixes` so skills auto-resolve identity without prompting the user.
+- **F1 — `validate_task_payload` validator tool** (commit `cf6c961`) — client-side payload validation before any write reaches Convex.
+
+See `mcp-server/CHANGELOG.md` for the full per-PR list.
+
 ## Install
 
 ### Option 1: npx (no install)
@@ -74,7 +88,7 @@ VantagePeers ships a built-in OAuth 2.1 authorization server so Claude.ai web ca
 
 The server also reads `CONVEX_URL` from `.env.local` in the parent directory if not set via environment.
 
-## Tools (84)
+## Tools (97)
 
 ### Memory (6)
 `store_memory`, `recall`, `list_memories`, `soft_delete_memory`, `get_memory`, `store_episode`

package/dist/server-http.d.ts

@@ -37,4 +37,5 @@ export declare function parseBasicAuthSecret(authHeader: string | undefined, bod
     clientId: string | null;
     clientSecret: string | null;
 };
+export declare function redirectUriMatches(registeredUri: string, presentedUri: string): boolean;
 export declare const app: Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;

package/dist/server-http.js

@@ -31,7 +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 { timingSafeEqual } from "@vantageos/cloud-identity";
 import { registerTools } from "./src/tools.js";
 import { listUiResources, readUiResource } from "./src/ui-resources/index.js";
 let pkg;
@@ -120,6 +120,54 @@ async function loadScopeProfile(profileId) {
     "oauth:getScopeProfile", { profileId }));
 }
 // ─────────────────────────────────────────────────────────────────────────────
+// D7 wildcard redirect_uri matcher
+//
+// RFC 6749 §3.1.2.3/§3.1.2.4 mandates that the authorization server validate
+// the inbound `redirect_uri` against the URIs registered for the client and
+// reject anything that does not match. The default match is byte-exact.
+//
+// Some MCP clients (notably ChatGPT's custom connector flow as of Day 92,
+// 2026-06-04) issue per-session callbacks under a stable path prefix with a
+// dynamic trailing segment, e.g. `https://chatgpt.com/connector/oauth/<id>`
+// where `<id>` rotates per connector instance. A pure exact-match policy
+// blocks every such flow after the first registration.
+//
+// To allow these flows without re-opening the open-redirect attack surface
+// that the exact-match rule was designed to close, a registered URI may
+// embed exactly one `*` token. When present, the URI is treated as a glob:
+//   - every other character is matched literally (regex-escaped),
+//   - the `*` is expanded to `[a-zA-Z0-9_-]+` — at least one char, no slash,
+//     no dot, no path separator, no host-bracketing punctuation,
+//   - the result is anchored with `^` and `$`.
+//
+// Lookalike attacks are still rejected because:
+//   - the host portion is literal, so `chatgpt.com.evil.io` does not match
+//     `https://chatgpt.com/connector/oauth/*`,
+//   - the path prefix is literal, so `/connector/oauth/../admin` does not
+//     match (`.` and `/` are not in the dynamic char class),
+//   - the dynamic segment requires at least one allowed character, so a
+//     trailing-slash variant (`.../oauth/`) does not match either.
+//
+// URIs without a `*` keep the original exact-match semantics — this helper
+// is a strict superset of the prior behavior.
+export function redirectUriMatches(registeredUri, presentedUri) {
+    if (!registeredUri.includes("*")) {
+        return registeredUri === presentedUri;
+    }
+    // Escape regex metacharacters EXCEPT `*`, then expand `*`.
+    const escaped = registeredUri.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+    const pattern = `^${escaped.replace(/\*/g, "[a-zA-Z0-9_-]+")}$`;
+    try {
+        return new RegExp(pattern).test(presentedUri);
+    }
+    catch {
+        return false;
+    }
+}
+function redirectUriMatchesAny(registeredUris, presentedUri) {
+    return registeredUris.some((u) => redirectUriMatches(u, presentedUri));
+}
+// ─────────────────────────────────────────────────────────────────────────────
 // App
 // ─────────────────────────────────────────────────────────────────────────────
 export const app = new Hono();
@@ -300,7 +348,8 @@ app.get("/authorize", async (c) => {
     // 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)) {
+    if (registeredUris.length === 0 ||
+        !redirectUriMatchesAny(registeredUris, redirectUri)) {
         return c.json({
             error: "invalid_request",
             error_description: "redirect_uri does not match a registered redirect URI for this client",
@@ -370,7 +419,7 @@ app.post("/token", async (c) => {
         if (Date.now() > record.expiresAt) {
             return c.json({ error: "invalid_grant", error_description: "code expired" }, 400);
         }
-        if (redirectUri && redirectUri !== record.redirectUri) {
+        if (redirectUri && !redirectUriMatches(record.redirectUri, redirectUri)) {
             return c.json({
                 error: "invalid_grant",
                 error_description: "redirect_uri mismatch",
@@ -409,8 +458,9 @@ app.post("/token", async (c) => {
                 }, 401);
             }
             const presentedHash = await sha256Hex(clientSecret);
+            const _enc = new TextEncoder();
             if (!client.clientSecretHash ||
-                !(await timingSafeEqual(presentedHash, client.clientSecretHash))) {
+                !(await timingSafeEqual(_enc.encode(presentedHash), _enc.encode(client.clientSecretHash)))) {
                 return c.json({
                     error: "invalid_client",
                     error_description: "client_secret mismatch",
@@ -497,8 +547,9 @@ app.post("/token", async (c) => {
                 }, 401);
             }
             const presentedHash = await sha256Hex(clientSecret);
+            const _enc = new TextEncoder();
             if (!refreshClient.clientSecretHash ||
-                !(await timingSafeEqual(presentedHash, refreshClient.clientSecretHash))) {
+                !(await timingSafeEqual(_enc.encode(presentedHash), _enc.encode(refreshClient.clientSecretHash)))) {
                 return c.json({
                     error: "invalid_client",
                     error_description: "client_secret mismatch",
@@ -657,6 +708,367 @@ admin.post("/oauth/seed-profiles", async (c) => {
     "oauth:seedDefaultProfiles", { callerToken: masterToken });
     return c.json({ created });
 });
+// ─────────────────────────────────────────────────────────────────────────────
+// S2.2 D5 — PATCH /admin/scope-profiles/:id
+//
+// HTTP wrapper around Convex mutation `oauth:patchScopeProfileEmergency`
+// (S1.2-mutation + S2.1 cascade + audit log).
+//
+// Auth: BEARER_SECRET_MASTER via masterOnlyMiddleware (already mounted on
+// the `admin` Hono sub-app). The mutation itself does a second constant-time
+// master-token check via `requireMasterAuth` at the Convex layer.
+//
+// Body schema:
+//   {
+//     rename?:                  string,
+//     fromAllowList?:           string[],
+//     namespaceReadPrefixes?:   string[],
+//     namespaceWritePrefixes?:  string[],
+//     cascadeRevokeTokens:      boolean,   // REQUIRED
+//     reason:                   string,    // REQUIRED, Convex enforces ≥40
+//   }
+//
+// Response (200):
+//   { patchedProfileId, cascadeRevokedCount, clientsRetargeted, auditLogId }
+//
+// Error mapping (Convex throw → HTTP status):
+//   "profile not found" → 404
+//   "D4 violation"      → 400
+//   "reason must be"    → 400  (reason length guard)
+//   anything else       → 500
+// ─────────────────────────────────────────────────────────────────────────────
+admin.patch("/scope-profiles/:id", async (c) => {
+    const masterToken = process.env.BEARER_SECRET_MASTER;
+    if (!masterToken)
+        return c.json({ error: "server_misconfigured" }, 500);
+    const profileId = c.req.param("id");
+    if (!profileId) {
+        return c.json({ error: "invalid_request", detail: "missing :id" }, 400);
+    }
+    let body = {};
+    try {
+        body = await c.req.json();
+    }
+    catch {
+        return c.json({ error: "invalid_request", detail: "body must be valid JSON" }, 400);
+    }
+    // Required: cascadeRevokeTokens (boolean), reason (string)
+    if (typeof body.cascadeRevokeTokens !== "boolean") {
+        return c.json({
+            error: "invalid_request",
+            detail: "cascadeRevokeTokens (boolean) is required",
+        }, 400);
+    }
+    if (typeof body.reason !== "string" || body.reason.length === 0) {
+        return c.json({ error: "invalid_request", detail: "reason (string) is required" }, 400);
+    }
+    // Optional fields — typed coercion / validation
+    const mutationArgs = {
+        callerToken: masterToken,
+        profileId,
+        cascadeRevokeTokens: body.cascadeRevokeTokens,
+        reason: body.reason,
+    };
+    if (body.rename !== undefined) {
+        if (typeof body.rename !== "string") {
+            return c.json({ error: "invalid_request", detail: "rename must be a string" }, 400);
+        }
+        mutationArgs.rename = body.rename;
+    }
+    for (const key of [
+        "fromAllowList",
+        "namespaceReadPrefixes",
+        "namespaceWritePrefixes",
+    ]) {
+        const v = body[key];
+        if (v !== undefined) {
+            if (!Array.isArray(v) || v.some((x) => typeof x !== "string")) {
+                return c.json({ error: "invalid_request", detail: `${key} must be string[]` }, 400);
+            }
+            mutationArgs[key] = v;
+        }
+    }
+    try {
+        const result = await internalClient().mutation(
+        // biome-ignore lint/suspicious/noExplicitAny: Convex string API
+        "oauth:patchScopeProfileEmergency", mutationArgs);
+        return c.json(result, 200);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        // Map known Convex throws to HTTP status
+        if (/profile not found/i.test(message)) {
+            return c.json({ error: "not_found", detail: message }, 404);
+        }
+        if (/D4 violation/i.test(message)) {
+            return c.json({ error: "D4 violation", detail: message }, 400);
+        }
+        if (/reason must be at least/i.test(message)) {
+            return c.json({ error: "invalid_request", detail: message }, 400);
+        }
+        console.error("[admin] patchScopeProfileEmergency failed:", message);
+        return c.json({ error: "server_error", detail: message }, 500);
+    }
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// POST /admin/oauth/access-tokens — direct mint (bypass full OAuth flow)
+//
+// Wraps Convex mutation `oauth:createAccessToken` so operators with the
+// master bearer can mint a scoped access token in a single call without
+// running the DCR → /authorize → /token dance.
+//
+// Use case: provisioning isolated test workspaces for manual cross-tenant
+// e2e verification, or onboarding a paying user when the dashboard does
+// not yet exist (cloud-launch-v1 close-out window).
+//
+// Auth: BEARER_SECRET_MASTER via masterOnlyMiddleware (mounted on /admin).
+//
+// Body schema:
+//   {
+//     scopeProfile:              string,   // REQUIRED — must exist in oauth_scope_profiles
+//     userId:                    string,   // REQUIRED — caller-supplied user identifier
+//     clientId?:                 string,   // optional — defaults to "admin-mint:<random>"
+//     scopes?:                   string[], // optional — defaults to ["mcp:full"]
+//     fromAllowList?:            string[], // optional — defaults to profile.fromAllowList
+//     namespaceReadPrefixes?:    string[], // optional — defaults to profile.namespaceReadPrefixes
+//     namespaceWritePrefixes?:   string[], // optional — defaults to profile.namespaceWritePrefixes
+//     expiresInSec?:             number,   // optional — defaults to 86400 (24h), max 30d
+//   }
+//
+// Response (201):
+//   {
+//     access_token:            <raw token, 64 hex chars — returned ONCE, never again>,
+//     token_type:              "Bearer",
+//     expires_at:              <unix ms>,
+//     expires_in:              <seconds>,
+//     clientId:                <effective>,
+//     userId:                  <effective>,
+//     scopes:                  <effective array>,
+//     scopeProfile:            <effective>,
+//     fromAllowList:           <effective array>,
+//     namespaceReadPrefixes:   <effective array>,
+//     namespaceWritePrefixes:  <effective array>
+//   }
+// ─────────────────────────────────────────────────────────────────────────────
+admin.post("/oauth/access-tokens", async (c) => {
+    const masterToken = process.env.BEARER_SECRET_MASTER;
+    if (!masterToken)
+        return c.json({ error: "server_misconfigured" }, 500);
+    let body = {};
+    try {
+        body = await c.req.json();
+    }
+    catch {
+        return c.json({ error: "invalid_request", detail: "body must be valid JSON" }, 400);
+    }
+    const scopeProfileArg = typeof body.scopeProfile === "string" ? body.scopeProfile : null;
+    const userId = typeof body.userId === "string" ? body.userId : null;
+    if (!scopeProfileArg || !userId) {
+        return c.json({
+            error: "invalid_request",
+            detail: "scopeProfile and userId are required",
+        }, 400);
+    }
+    const loadedProfile = await loadScopeProfile(scopeProfileArg);
+    if (!loadedProfile) {
+        return c.json({ error: "invalid_scope_profile", scopeProfile: scopeProfileArg }, 400);
+    }
+    const profile = loadedProfile;
+    const clientId = typeof body.clientId === "string"
+        ? body.clientId
+        : `admin-mint:${crypto.randomUUID()}`;
+    const scopes = Array.isArray(body.scopes)
+        ? body.scopes.filter((x) => typeof x === "string")
+        : ["mcp:full"];
+    const arrayOrProfile = (key) => {
+        const v = body[key];
+        if (Array.isArray(v) && v.every((x) => typeof x === "string")) {
+            return v;
+        }
+        return profile[key];
+    };
+    const fromAllowList = arrayOrProfile("fromAllowList");
+    const namespaceReadPrefixes = arrayOrProfile("namespaceReadPrefixes");
+    const namespaceWritePrefixes = arrayOrProfile("namespaceWritePrefixes");
+    const expiresInSecRaw = typeof body.expiresInSec === "number" ? body.expiresInSec : 86400;
+    const MAX_EXPIRES_IN_SEC = 30 * 86400;
+    if (expiresInSecRaw <= 0 || expiresInSecRaw > MAX_EXPIRES_IN_SEC) {
+        return c.json({
+            error: "invalid_request",
+            detail: `expiresInSec must be in (0, ${MAX_EXPIRES_IN_SEC}]`,
+        }, 400);
+    }
+    const expiresAt = Date.now() + expiresInSecRaw * 1000;
+    const accessToken = randomOpaqueToken();
+    const tokenHash = await sha256Hex(accessToken);
+    try {
+        await internalClient().mutation(
+        // biome-ignore lint/suspicious/noExplicitAny: Convex string API
+        "oauth:createAccessToken", {
+            callerToken: masterToken,
+            tokenHash,
+            clientId,
+            userId,
+            scopes,
+            scopeProfile: scopeProfileArg,
+            fromAllowList,
+            namespaceReadPrefixes,
+            namespaceWritePrefixes,
+            expiresAt,
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error("[admin] createAccessToken failed:", message);
+        return c.json({ error: "server_error", detail: message }, 500);
+    }
+    return c.json({
+        access_token: accessToken,
+        token_type: "Bearer",
+        expires_at: expiresAt,
+        expires_in: expiresInSecRaw,
+        clientId,
+        userId,
+        scopes,
+        scopeProfile: scopeProfileArg,
+        fromAllowList,
+        namespaceReadPrefixes,
+        namespaceWritePrefixes,
+    }, 201);
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// POST /admin/oauth/clients/:clientId/patch-scope — Day 92 LIVE
+//
+// Wraps Convex mutation `oauth:patchClientScopeAndRefreshTokens`. Re-targets
+// the client to a new scope_profile and propagates the new
+// `fromAllowList` + namespace prefixes into every live access token row
+// for that clientId WITHOUT revoking refresh tokens — the bearer the
+// operator already pasted into their MCP host keeps working, immediately
+// gaining the new profile's allow list. Eliminates the customer
+// re-paste step that profile rotation would otherwise force.
+//
+// Auth: BEARER_SECRET_MASTER via masterOnlyMiddleware.
+//
+// Body schema: { newScopeProfile: string, reason: string (≥20 chars) }
+//
+// Response (200): {
+//   clientPatched, previousScopeProfile, newScopeProfile,
+//   accessTokensRefreshed, auditLogId
+// }
+//
+// Error mapping (Convex throw → HTTP status):
+//   "client not found"      → 404
+//   "client is revoked"     → 410 (Gone — re-mint required)
+//   "scope_profile not found" → 400
+//   "reason must be at least 20" → 400
+//   anything else           → 500
+// ─────────────────────────────────────────────────────────────────────────────
+admin.post("/oauth/clients/:clientId/patch-scope", async (c) => {
+    const masterToken = process.env.BEARER_SECRET_MASTER;
+    if (!masterToken)
+        return c.json({ error: "server_misconfigured" }, 500);
+    const clientId = c.req.param("clientId");
+    if (!clientId) {
+        return c.json({ error: "invalid_request", detail: "missing :clientId" }, 400);
+    }
+    let body = {};
+    try {
+        body = await c.req.json();
+    }
+    catch {
+        return c.json({ error: "invalid_request", detail: "body must be valid JSON" }, 400);
+    }
+    const newScopeProfile = typeof body.newScopeProfile === "string" ? body.newScopeProfile : null;
+    const reason = typeof body.reason === "string" ? body.reason : null;
+    if (!newScopeProfile || !reason) {
+        return c.json({
+            error: "invalid_request",
+            detail: "newScopeProfile and reason are required",
+        }, 400);
+    }
+    try {
+        const result = await internalClient().mutation(
+        // biome-ignore lint/suspicious/noExplicitAny: Convex string API
+        "oauth:patchClientScopeAndRefreshTokens", {
+            callerToken: masterToken,
+            clientId,
+            newScopeProfile,
+            reason,
+        });
+        return c.json(result, 200);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (/client not found/i.test(message)) {
+            return c.json({ error: "not_found", detail: message }, 404);
+        }
+        if (/client is revoked/i.test(message)) {
+            return c.json({ error: "gone", detail: message }, 410);
+        }
+        if (/scope_profile not found/i.test(message)) {
+            return c.json({ error: "invalid_scope_profile", detail: message }, 400);
+        }
+        if (/reason must be at least/i.test(message)) {
+            return c.json({ error: "invalid_request", detail: message }, 400);
+        }
+        console.error("[admin] patchClientScopeAndRefreshTokens failed:", message);
+        return c.json({ error: "server_error", detail: message }, 500);
+    }
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// POST /admin/oauth/clients/:clientId/revoke-access-tokens-only — Day 92 LIVE
+//
+// Wraps Convex mutation `oauth:revokeAccessTokensOnly`. Force-rotates every
+// live access token for the client by setting `revokedAt`, while leaving
+// refresh tokens untouched. The next API call from the connector hits 401
+// → connector silently runs the OAuth refresh-flow → fresh access token
+// minted from the current client scope_profile + catalog. Combined with
+// `patchClientScopeAndRefreshTokens` (which retargeted
+// refresh_tokens.scopeProfile in commit 40413bd) the next mint observes
+// the new profile end-to-end with zero customer re-paste.
+//
+// Auth: BEARER_SECRET_MASTER via masterOnlyMiddleware.
+//
+// Body schema: { reason: string (≥20 chars) }
+// Response (200): { clientId, accessTokensRevoked, refreshTokensPreserved }
+// ─────────────────────────────────────────────────────────────────────────────
+admin.post("/oauth/clients/:clientId/revoke-access-tokens-only", async (c) => {
+    const masterToken = process.env.BEARER_SECRET_MASTER;
+    if (!masterToken)
+        return c.json({ error: "server_misconfigured" }, 500);
+    const clientId = c.req.param("clientId");
+    if (!clientId) {
+        return c.json({ error: "invalid_request", detail: "missing :clientId" }, 400);
+    }
+    let body = {};
+    try {
+        body = await c.req.json();
+    }
+    catch {
+        return c.json({ error: "invalid_request", detail: "body must be valid JSON" }, 400);
+    }
+    const reason = typeof body.reason === "string" ? body.reason : null;
+    if (!reason) {
+        return c.json({ error: "invalid_request", detail: "reason is required" }, 400);
+    }
+    try {
+        const result = await internalClient().mutation(
+        // biome-ignore lint/suspicious/noExplicitAny: Convex string API
+        "oauth:revokeAccessTokensOnly", { callerToken: masterToken, clientId, reason });
+        return c.json(result, 200);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (/client not found/i.test(message)) {
+            return c.json({ error: "not_found", detail: message }, 404);
+        }
+        if (/reason must be at least/i.test(message)) {
+            return c.json({ error: "invalid_request", detail: message }, 400);
+        }
+        console.error("[admin] revokeAccessTokensOnly failed:", message);
+        return c.json({ error: "server_error", detail: message }, 500);
+    }
+});
 app.route("/admin", admin);
 // ─────────────────────────────────────────────────────────────────────────────
 // MCP endpoint — authenticated, stateless per-request server

package/dist/server.js

@@ -102,7 +102,7 @@ const convexUrl = loadConvexUrl();
 const convex = new ConvexHttpClient(convexUrl);
 const server = new McpServer({
     name: "vantage-peers",
-    version: "2.0.0",
+    version: "2.5.0",
 });
 // ─────────────────────────────────────────────────────────────────────────────
 // Helper: structured error response for MCP tool handlers
@@ -493,7 +493,7 @@ server.tool("list_memories", "List active memories for a namespace, ordered newe
 // ─────────────────────────────────────────────────────────────────────────────
 server.tool("send_message", "Send a message to one, many, or all orchestrators. " +
     "channel: 'broadcast' = all, 'tau' = role DM, 'pi-vps' = instance DM, 'tau,phi' = multi. " +
-    "Creates message + one receipt per recipient. Replaces claude-peers send_message.", {
+    "Creates message + one receipt per recipient. Supersedes legacy send_message (pre-VantagePeers).", {
     from: creatorSchema.describe("Sender role (e.g. pi, tau, phi, sigma, omega, zeta, eta, kappa, alpha, lambda, victor, or any custom role)"),
     fromInstanceId: z
         .string()
@@ -540,7 +540,7 @@ server.tool("send_message", "Send a message to one, many, or all orchestrators.
 // ─────────────────────────────────────────────────────────────────────────────
 server.tool("check_messages", "Check for unread messages. Returns messages with receiptIds for marking as read. " +
     "If recipientInstanceId is provided, returns instance-targeted + role-level messages. " +
-    "Replaces claude-peers check_messages.", {
+    "Supersedes legacy check_messages (pre-VantagePeers).", {
     recipient: creatorSchema.describe("Orchestrator role (e.g. pi, tau, phi, sigma, omega, zeta, eta, kappa, alpha, lambda, victor, or any custom role)"),
     recipientInstanceId: z
         .string()
@@ -679,7 +679,7 @@ server.tool("set_summary", "Set a brief summary of what you are currently workin
 // Tool: list_peers
 // ─────────────────────────────────────────────────────────────────────────────
 server.tool("list_peers", "List all orchestrator profiles with their current status and summary. " +
-    "Replaces claude-peers list_peers.", {}, async () => {
+    "Supersedes legacy list_peers (pre-VantagePeers).", {}, async () => {
     try {
         const profiles = await convex.query("profiles:listProfiles", {});
         const peers = profiles.map((p) => ({

package/dist/src/auth.js

@@ -17,6 +17,7 @@
  * 401 is returned with a WWW-Authenticate header per RFC 6750 §3 so Claude.ai's
  * OAuth connector can bootstrap discovery.
  */
+import { validateMasterBearer } from "@vantageos/cloud-identity";
 import { ConvexHttpClient } from "convex/browser";
 // ─────────────────────────────────────────────────────────────────────────────
 // Internal Convex client (reads mcpTenants + oauth_* tables)
@@ -329,16 +330,22 @@ export function bearerAuthMiddleware() {
 // ─────────────────────────────────────────────────────────────────────────────
 export function masterOnlyMiddleware() {
     return async (c, next) => {
-        const authHeader = c.req.header("Authorization");
         const masterToken = process.env.BEARER_SECRET_MASTER;
         if (!masterToken) {
             return c.json({ error: "Server misconfigured: BEARER_SECRET_MASTER not set" }, 500);
         }
-        if (!authHeader?.startsWith("Bearer ")) {
-            return c.json({ error: "Missing Authorization header" }, 401);
-        }
-        const token = authHeader.slice("Bearer ".length).trim();
-        if (token !== masterToken) {
+        // SECURITY UPGRADE (S2.3 D8): validateMasterBearer from
+        // @vantageos/cloud-identity sha256-hashes both the presented token and
+        // the configured master secret, then constant-time-compares the digests.
+        // Replaces the previous non-constant-time `token !== masterToken`
+        // string compare.
+        const authHeader = c.req.header("Authorization");
+        const result = await validateMasterBearer(authHeader, masterToken);
+        if (!result.ok) {
+            if (result.error === "missing" || result.error === "malformed") {
+                return c.json({ error: "Missing Authorization header" }, 401);
+            }
+            // "mismatch"
             return c.json({ error: "Forbidden: admin endpoints require master token" }, 403);
         }
         await next();