@nexvora/mcp-server 0.3.2 → 0.4.0

package/src/NexvoraClient.ts

@@ -1,328 +0,0 @@
-import { z } from "zod";
-
-import { type Config, type IConfigStore } from "./config.js";
-
-export type AuditOutcome = "success" | "error" | "rate_limited" | "unauthorized";
-
-const AuditPayloadSchema = z.object({
-  toolName: z.string().min(1),
-  outcome: z.enum(["success", "error", "rate_limited", "unauthorized"]),
-  agentId: z.string().uuid().optional(),
-  durationMs: z.number().int().positive().optional(),
-  errorCode: z.string().optional(),
-});
-
-export type AuditPayload = z.infer<typeof AuditPayloadSchema>;
-
-export interface NexvoraClientOptions {
-  /** Base URL of the NexVora backend (e.g. https://api.nxvora.online) */
-  baseUrl: string;
-  /** JWT access token for the authenticated user */
-  accessToken: string;
-  /** UUID of the donor agent making tool calls (optional) */
-  agentId?: string;
-  /**
-   * Optional config store for token-refresh support.
-   * When omitted the client uses the static accessToken only (no refresh).
-   */
-  configStore?: IConfigStore;
-}
-
-interface RefreshTokenResponse {
-  accessToken: string;
-  refreshToken: string;
-  expiresAt: number;
-}
-
-/** Thrown when the refresh token itself is expired or revoked. */
-export class SessionExpiredError extends Error {
-  constructor() {
-    super(
-      "Your NexVora session has expired. Run `nexvora login` to reconnect.",
-    );
-    this.name = "SessionExpiredError";
-  }
-}
-
-/**
- * Thrown when a PAT (Personal Access Token) is rejected as expired or revoked.
- *
- * <p>PATs do not refresh automatically — when one returns 401 the user must
- * regenerate it from the web UI. The message includes the exact URL so the
- * MCP host can surface it directly to the user without them having to dig.</p>
- */
-export class PatRevokedOrExpiredError extends Error {
-  constructor() {
-    super(
-      "Your NexVora PAT was rejected — it has been revoked or expired. " +
-        "Generate a new one at https://app.nxvora.online/app/settings/mcp-tokens " +
-        "and paste it into NEXVORA_ACCESS_TOKEN in your mcp.json.",
-    );
-    this.name = "PatRevokedOrExpiredError";
-  }
-}
-
-/**
- * Thrown when the backend returns 403 with type=pat-scope-missing, indicating
- * the PAT is valid but is not authorised for the tool the user just invoked.
- *
- * <p>The exact missing scope is included so the MCP host can render an
- * actionable "add tool:foo to your PAT" message.</p>
- */
-export class PatScopeMissingError extends Error {
-  constructor(public readonly requiredScope: string) {
-    super(
-      `Your NexVora PAT is missing the required scope: ${requiredScope}. ` +
-        "Generate a new PAT with this scope checked at " +
-        "https://app.nxvora.online/app/settings/mcp-tokens.",
-    );
-    this.name = "PatScopeMissingError";
-  }
-}
-
-/** Wire-format prefix that identifies a PAT (as opposed to a session JWT). */
-const PAT_PREFIX = "nxv_pat_";
-
-/** {@code true} if the supplied access token is a Personal Access Token. */
-function isPat(accessToken: string): boolean {
-  return accessToken.startsWith(PAT_PREFIX);
-}
-
-/**
- * Thin HTTP client for the NexVora backend.
- *
- * When constructed with a {@link IConfigStore} it automatically refreshes
- * expired access tokens — proactively (60 s before expiry) and reactively
- * (on a first 401). Only one refresh round-trip is made even when concurrent
- * requests all receive a 401 at the same time.
- */
-export class NexvoraClient {
-  private readonly baseUrl: string;
-  private accessToken: string;
-  readonly agentId?: string;
-  private readonly configStore?: IConfigStore;
-
-  /** Guards against concurrent refresh requests — shared across all in-flight calls. */
-  private refreshPromise: Promise<void> | null = null;
-
-  constructor(options: NexvoraClientOptions) {
-    this.baseUrl = options.baseUrl.replace(/\/$/, "");
-    this.accessToken = options.accessToken;
-    this.agentId = options.agentId;
-    this.configStore = options.configStore;
-  }
-
-  private authHeaders(): Record<string, string> {
-    return {
-      "Content-Type": "application/json",
-      Authorization: `Bearer ${this.accessToken}`,
-    };
-  }
-
-  // ── Token refresh ──────────────────────────────────────────────────────────
-
-  private async ensureTokenFresh(): Promise<void> {
-    // PATs never refresh — their lifetime is exactly the expiry on the
-    // mcp_pats row. Trying to /auth/refresh with a PAT would fail and
-    // confuse the user with a misleading "session expired" error.
-    if (isPat(this.accessToken)) return;
-    if (!this.configStore) return;
-    let config: Config;
-    try {
-      config = this.configStore.read();
-    } catch {
-      return; // no config file yet — continue with the static token
-    }
-    const nowSecs = Math.floor(Date.now() / 1000);
-    if (config.expiresAt < nowSecs + 60) {
-      await this.triggerRefresh(config);
-    }
-  }
-
-  /**
-   * Ensures only one refresh is in-flight at a time.
-   * Concurrent callers await the same promise.
-   */
-  private triggerRefresh(config?: Config): Promise<void> {
-    if (!this.refreshPromise) {
-      this.refreshPromise = this.performRefresh(config).finally(() => {
-        this.refreshPromise = null;
-      });
-    }
-    return this.refreshPromise;
-  }
-
-  private async performRefresh(existingConfig?: Config): Promise<void> {
-    if (!this.configStore) return;
-
-    let config: Config;
-    try {
-      config = existingConfig ?? this.configStore.read();
-    } catch {
-      throw new SessionExpiredError();
-    }
-
-    const response = await fetch(`${this.baseUrl}/auth/refresh`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ refreshToken: config.refreshToken }),
-    });
-
-    if (!response.ok) {
-      throw new SessionExpiredError();
-    }
-
-    const { accessToken, refreshToken, expiresAt } =
-      (await response.json()) as RefreshTokenResponse;
-
-    this.accessToken = accessToken;
-    this.configStore.write({ ...config, accessToken, refreshToken, expiresAt });
-  }
-
-  // ── Core request dispatcher ────────────────────────────────────────────────
-
-  private async dispatchFetch(url: string, init: RequestInit): Promise<Response> {
-    await this.ensureTokenFresh();
-
-    let response = await fetch(url, { ...init, headers: this.authHeaders() });
-
-    if (response.status === 401) {
-      // PATs never refresh — a 401 means the token is revoked or expired.
-      // Surface a targeted error pointing at the regen URL rather than the
-      // generic "session expired, run nexvora login" message that suits
-      // JWT users.
-      if (isPat(this.accessToken)) {
-        throw new PatRevokedOrExpiredError();
-      }
-      // JWT path: try one refresh then retry the original request once.
-      if (this.configStore) {
-        await this.triggerRefresh();
-        response = await fetch(url, { ...init, headers: this.authHeaders() });
-      }
-    }
-
-    // 403 with type=pat-scope-missing carries the exact scope the PAT lacks.
-    // Pull it out so we can throw a typed error that downstream tools can
-    // render as "your PAT needs tool:foo — regenerate at <url>".
-    if (response.status === 403 && isPat(this.accessToken)) {
-      const scope = await readMissingScope(response);
-      if (scope != null) {
-        throw new PatScopeMissingError(scope);
-      }
-    }
-
-    return response;
-  }
-
-  // ── Public API ─────────────────────────────────────────────────────────────
-
-  /**
-   * Sends an audit event to {@code POST /mcp/audit} fire-and-forget.
-   * Errors are silently swallowed to prevent audit failures from affecting tool callers.
-   */
-  async sendAudit(payload: AuditPayload): Promise<void> {
-    try {
-      const validated = AuditPayloadSchema.parse(payload);
-      await fetch(`${this.baseUrl}/mcp/audit`, {
-        method: "POST",
-        headers: this.authHeaders(),
-        body: JSON.stringify(validated),
-      });
-    } catch {
-      // audit failures must not surface to the tool caller
-    }
-  }
-
-  /**
-   * Makes an authenticated POST request to the NexVora backend.
-   *
-   * @throws {NexvoraApiError} on non-2xx responses
-   * @throws {SessionExpiredError} when the refresh token is also expired
-   */
-  async post<T>(path: string, body: unknown): Promise<T> {
-    const response = await this.dispatchFetch(`${this.baseUrl}${path}`, {
-      method: "POST",
-      body: JSON.stringify(body),
-    });
-
-    if (!response.ok) {
-      const text = await response.text().catch(() => "");
-      throw new NexvoraApiError(response.status, text, path);
-    }
-
-    return response.json() as Promise<T>;
-  }
-
-  /**
-   * Makes an authenticated GET request to the NexVora backend.
-   *
-   * @throws {NexvoraApiError} on non-2xx responses
-   * @throws {SessionExpiredError} when the refresh token is also expired
-   */
-  async get<T>(path: string): Promise<T> {
-    const response = await this.dispatchFetch(`${this.baseUrl}${path}`, {});
-
-    if (!response.ok) {
-      const text = await response.text().catch(() => "");
-      throw new NexvoraApiError(response.status, text, path);
-    }
-
-    return response.json() as Promise<T>;
-  }
-}
-
-/**
- * Reads a 403 response body as RFC 7807 ProblemDetail and pulls the
- * {@code required_scope} property out. Returns {@code null} for any other
- * shape — the caller falls back to the generic error path.
- *
- * <p>The response body is consumed by this call; the dispatcher must not
- * attempt to read it again. We clone first so the original {@link Response}
- * remains usable if no scope is found.</p>
- */
-async function readMissingScope(response: Response): Promise<string | null> {
-  try {
-    const cloned = response.clone();
-    const body = (await cloned.json()) as {
-      type?: string;
-      required_scope?: string;
-    };
-    if (
-      typeof body?.required_scope === "string" &&
-      body.type?.includes("pat-scope-missing")
-    ) {
-      return body.required_scope;
-    }
-  } catch {
-    // not JSON, or fetch couldn't be cloned — fall through
-  }
-  return null;
-}
-
-/**
- * Represents a non-2xx response from the NexVora API.
- */
-export class NexvoraApiError extends Error {
-  constructor(
-    public readonly statusCode: number,
-    public readonly body: string,
-    public readonly path: string,
-  ) {
-    super(`NexVora API error ${statusCode} on ${path}: ${body}`);
-    this.name = "NexvoraApiError";
-  }
-
-  get isRateLimited(): boolean {
-    return this.statusCode === 429;
-  }
-
-  get isUnauthorized(): boolean {
-    return this.statusCode === 401 || this.statusCode === 403;
-  }
-
-  toAuditOutcome(): AuditOutcome {
-    if (this.isRateLimited) return "rate_limited";
-    if (this.isUnauthorized) return "unauthorized";
-    return "error";
-  }
-}

package/src/RateLimiter.ts

@@ -1,74 +0,0 @@
-export const DEFAULT_RATE_LIMITS: Record<string, number> = {
-  nexvora_wallet_balance: 60,
-  nexvora_observatory: 60,
-  nexvora_agentstack_search: 30,
-  nexvora_agentstack_ask: 5,
-  nexvora_agentstack_answer: 10,
-  nexvora_feed_post: 10,
-  nexvora_feed_react: 60,
-  nexvora_consulting_search: 30,
-  nexvora_consulting_book: 5,
-  nexvora_knowledge_search: 30,
-  nexvora_knowledge_subscribe: 5,
-};
-
-export type ConsumeResult = { allowed: true } | { allowed: false; retryAfterMs: number };
-
-/**
- * Smooth token-bucket with continuous refill.
- *
- * Capacity = perMinuteLimit (burst up to the full window's worth of tokens).
- * Refill rate = perMinuteLimit / 60 tokens-per-second (smooth, not batch).
- */
-export class TokenBucket {
-  private tokens: number;
-  private lastRefill: number;
-
-  constructor(
-    private readonly capacity: number,
-    private readonly refillRatePerSec: number,
-  ) {
-    this.tokens = capacity;
-    this.lastRefill = Date.now();
-  }
-
-  tryConsume(): ConsumeResult {
-    this.refill();
-    if (this.tokens >= 1) {
-      this.tokens -= 1;
-      return { allowed: true };
-    }
-    // milliseconds until 1 token is available
-    const retryAfterMs = Math.ceil(((1 - this.tokens) / this.refillRatePerSec) * 1000);
-    return { allowed: false, retryAfterMs };
-  }
-
-  private refill(): void {
-    const now = Date.now();
-    const elapsedSec = (now - this.lastRefill) / 1000;
-    this.tokens = Math.min(this.capacity, this.tokens + elapsedSec * this.refillRatePerSec);
-    this.lastRefill = now;
-  }
-}
-
-/**
- * One TokenBucket per registered tool name.
- * Tools not in the registry are always allowed.
- */
-export class RateLimiterRegistry {
-  private readonly buckets = new Map<string, TokenBucket>();
-
-  constructor(limits: Record<string, number> = DEFAULT_RATE_LIMITS) {
-    for (const [toolName, perMinute] of Object.entries(limits)) {
-      if (perMinute > 0) {
-        this.buckets.set(toolName, new TokenBucket(perMinute, perMinute / 60));
-      }
-    }
-  }
-
-  tryConsume(toolName: string): ConsumeResult {
-    const bucket = this.buckets.get(toolName);
-    if (!bucket) return { allowed: true };
-    return bucket.tryConsume();
-  }
-}