@opsee/mcp-server 0.6.9 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opsee/mcp-server",
-  "version": "0.6.9",
+  "version": "0.7.1",
   "description": "Opsee MCP server — manage projects, tasks, docs, and cycles from AI coding environments",
   "type": "module",
   "bin": {
@@ -21,6 +21,7 @@
     "@modelcontextprotocol/sdk": "^1.12.1",
     "cors": "^2.8.6",
     "express": "^5.2.1",
+    "ioredis": "^5.11.1",
     "open": "^10.1.0",
     "tsx": "^4.21.0",
     "zod": "^4.3.6"

package/src/auth/__tests__/oauth-provider.test.ts

@@ -0,0 +1,182 @@
+import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
+import type { Response } from "express";
+import { InMemoryKVStore } from "../kv-store.js";
+import { OpseeClientStore, OpseeOAuthProvider } from "../oauth-provider.js";
+import type { OAuthClientInformationFull } from "@modelcontextprotocol/sdk/shared/auth.js";
+
+const SERVER_URL = "https://mcp.example.com";
+const REDIRECT_URI = "https://claude.ai/api/mcp/auth_callback";
+
+function makeClient(): Omit<
+  OAuthClientInformationFull,
+  "client_id" | "client_id_issued_at"
+> {
+  return {
+    redirect_uris: [REDIRECT_URI],
+    token_endpoint_auth_method: "none",
+    grant_types: ["authorization_code"],
+    response_types: ["code"],
+  } as unknown as Omit<
+    OAuthClientInformationFull,
+    "client_id" | "client_id_issued_at"
+  >;
+}
+
+describe("InMemoryKVStore", () => {
+  test("stores and retrieves values", async () => {
+    const store = new InMemoryKVStore();
+    await store.set("k", "v");
+    expect(await store.get("k")).toBe("v");
+  });
+
+  test("returns null for missing keys", async () => {
+    const store = new InMemoryKVStore();
+    expect(await store.get("nope")).toBeNull();
+  });
+
+  test("deletes values", async () => {
+    const store = new InMemoryKVStore();
+    await store.set("k", "v");
+    await store.del("k");
+    expect(await store.get("k")).toBeNull();
+  });
+
+  test("expires values after the TTL elapses", async () => {
+    vi.useFakeTimers();
+    const store = new InMemoryKVStore();
+    await store.set("k", "v", 10); // 10 second TTL
+    expect(await store.get("k")).toBe("v");
+    vi.advanceTimersByTime(11_000);
+    expect(await store.get("k")).toBeNull();
+    vi.useRealTimers();
+  });
+});
+
+describe("OpseeClientStore", () => {
+  test("registerClient persists redirect_uris and getClient round-trips them", async () => {
+    const store = new InMemoryKVStore();
+    const clientStore = new OpseeClientStore(store);
+
+    const registered = await clientStore.registerClient(makeClient());
+    expect(registered.client_id).toBeTruthy();
+    expect(registered.client_secret).toBeTruthy();
+
+    const fetched = await clientStore.getClient(registered.client_id);
+    expect(fetched).toBeDefined();
+    // The actual fix: the registered redirect_uri survives the round-trip, so
+    // the SDK's `redirect_uris.includes(redirect_uri)` check passes.
+    expect(fetched?.redirect_uris).toContain(REDIRECT_URI);
+  });
+
+  test("getClient returns undefined for an unknown client (no empty-uri fallback)", async () => {
+    const store = new InMemoryKVStore();
+    const clientStore = new OpseeClientStore(store);
+    expect(await clientStore.getClient("never-registered")).toBeUndefined();
+  });
+});
+
+describe("OpseeOAuthProvider flow", () => {
+  let store: InMemoryKVStore;
+  let provider: OpseeOAuthProvider;
+  let client: OAuthClientInformationFull;
+
+  beforeEach(async () => {
+    store = new InMemoryKVStore();
+    provider = new OpseeOAuthProvider(SERVER_URL, store, "https://app.example.com");
+    client = await (provider.clientsStore as OpseeClientStore).registerClient(
+      makeClient(),
+    );
+  });
+
+  // Captures the pendingId the provider embedded in the login redirect URL.
+  async function authorizeAndGetPendingId(): Promise<string> {
+    let location = "";
+    const res = {
+      redirect: (url: string) => {
+        location = url;
+      },
+    } as unknown as Response;
+
+    await provider.authorize(
+      client,
+      {
+        redirectUri: REDIRECT_URI,
+        codeChallenge: "challenge-123",
+        state: "state-xyz",
+      },
+      res,
+    );
+
+    expect(location).toContain("https://app.example.com/auth/mcp");
+    const callback = new URL(
+      decodeURIComponent(location.split("callback=")[1]),
+    );
+    const pendingId = callback.searchParams.get("pending");
+    expect(pendingId).toBeTruthy();
+    return pendingId as string;
+  }
+
+  test("authorize → callback → exchange issues the backend token", async () => {
+    const pendingId = await authorizeAndGetPendingId();
+
+    const result = await provider.handleCallback(
+      pendingId,
+      "backend.jwt.token",
+      "user-1",
+      "company-1",
+      "",
+    );
+    expect("redirectUri" in result).toBe(true);
+    const redirectUri = (result as { redirectUri: string }).redirectUri;
+
+    const url = new URL(redirectUri);
+    expect(url.searchParams.get("state")).toBe("state-xyz");
+    const code = url.searchParams.get("code");
+    expect(code).toBeTruthy();
+
+    // PKCE challenge is recoverable for the issued code.
+    expect(await provider.challengeForAuthorizationCode(client, code as string)).toBe(
+      "challenge-123",
+    );
+
+    const tokens = await provider.exchangeAuthorizationCode(client, code as string);
+    expect(tokens.access_token).toBe("backend.jwt.token");
+    expect(tokens.token_type).toBe("bearer");
+  });
+
+  test("authorization codes are single-use", async () => {
+    const pendingId = await authorizeAndGetPendingId();
+    const result = await provider.handleCallback(pendingId, "t", "u", "c", "");
+    const code = new URL((result as { redirectUri: string }).redirectUri).searchParams.get(
+      "code",
+    ) as string;
+
+    await provider.exchangeAuthorizationCode(client, code);
+    await expect(provider.exchangeAuthorizationCode(client, code)).rejects.toThrow(
+      /Invalid or expired authorization code/,
+    );
+  });
+
+  test("a pendingId cannot be replayed", async () => {
+    const pendingId = await authorizeAndGetPendingId();
+    await provider.handleCallback(pendingId, "t", "u", "c", "");
+    const second = await provider.handleCallback(pendingId, "t", "u", "c", "");
+    expect("error" in second).toBe(true);
+  });
+
+  test("revoked tokens fail verification", async () => {
+    // Build a JWT-shaped token with a future exp so only revocation can reject it.
+    const future = Math.floor(Date.now() / 1000) + 3600;
+    const payload = Buffer.from(
+      JSON.stringify({ exp: future, userId: "u", companyId: "c" }),
+    ).toString("base64url");
+    const token = `header.${payload}.sig`;
+
+    await expect(provider.verifyAccessToken(token)).resolves.toMatchObject({
+      clientId: "opsee",
+    });
+
+    await provider.revokeToken(client, { token });
+    await expect(provider.verifyAccessToken(token)).rejects.toThrow(/revoked/);
+  });
+});

package/src/auth/kv-store.ts

@@ -0,0 +1,103 @@
+import { Redis } from "ioredis";
+
+/**
+ * Minimal key/value store used to persist OAuth state.
+ *
+ * The OAuth flow keeps clients, pending authorizations, authorization codes,
+ * and revoked tokens here. Backing it with Redis (instead of in-process Maps)
+ * lets registration on one request survive a server restart and be visible to
+ * other replicas — which is what makes horizontal scaling safe.
+ */
+export interface KVStore {
+  /** Returns the stored value, or null if missing/expired. */
+  get(key: string): Promise<string | null>;
+  /** Stores a value, optionally expiring it after `ttlSeconds`. */
+  set(key: string, value: string, ttlSeconds?: number): Promise<void>;
+  /** Deletes a key. No-op if absent. */
+  del(key: string): Promise<void>;
+}
+
+/**
+ * Process-local fallback used when Redis is not configured (local dev, stdio
+ * usage). State is lost on restart and is NOT shared across replicas, so this
+ * must not be used in a multi-replica deployment.
+ */
+export class InMemoryKVStore implements KVStore {
+  private entries = new Map<string, { value: string; expiresAt: number | null }>();
+
+  async get(key: string): Promise<string | null> {
+    const entry = this.entries.get(key);
+    if (!entry) return null;
+    if (entry.expiresAt !== null && Date.now() > entry.expiresAt) {
+      this.entries.delete(key);
+      return null;
+    }
+    return entry.value;
+  }
+
+  async set(key: string, value: string, ttlSeconds?: number): Promise<void> {
+    const expiresAt =
+      ttlSeconds !== undefined ? Date.now() + ttlSeconds * 1000 : null;
+    this.entries.set(key, { value, expiresAt });
+  }
+
+  async del(key: string): Promise<void> {
+    this.entries.delete(key);
+  }
+}
+
+/** Redis-backed store. Expiry is delegated to Redis via the EX option. */
+export class RedisKVStore implements KVStore {
+  constructor(private readonly redis: Redis) {}
+
+  async get(key: string): Promise<string | null> {
+    return this.redis.get(key);
+  }
+
+  async set(key: string, value: string, ttlSeconds?: number): Promise<void> {
+    if (ttlSeconds !== undefined) {
+      await this.redis.set(key, value, "EX", ttlSeconds);
+    } else {
+      await this.redis.set(key, value);
+    }
+  }
+
+  async del(key: string): Promise<void> {
+    await this.redis.del(key);
+  }
+}
+
+/**
+ * Builds a KVStore from the environment. Uses Redis when REDIS_HOST is set,
+ * mirroring the backend's REDIS_* env conventions; otherwise falls back to an
+ * in-process store and warns that scaling beyond one replica is unsafe.
+ */
+export function createKVStore(): KVStore {
+  const host = process.env.REDIS_HOST;
+  if (!host) {
+    console.warn(
+      "[oauth] REDIS_HOST not set — using in-memory OAuth state. " +
+        "OAuth registrations will not survive restarts or scale beyond one replica.",
+    );
+    return new InMemoryKVStore();
+  }
+
+  const redis = new Redis({
+    host,
+    port: parseInt(process.env.REDIS_PORT || "6379", 10),
+    password: process.env.REDIS_PASSWORD || undefined,
+    db: parseInt(process.env.REDIS_DB || "0", 10),
+    tls: process.env.REDIS_TLS === "true" ? {} : undefined,
+    // Don't queue commands forever if Redis is unreachable; surface errors.
+    maxRetriesPerRequest: 3,
+  });
+
+  redis.on("error", (err: Error) => {
+    console.error("[oauth] Redis error:", err.message);
+  });
+  redis.on("connect", () => {
+    console.log(`[oauth] Connected to Redis at ${host}`);
+  });
+
+  return new RedisKVStore(redis);
+}

package/src/auth/oauth-provider.ts

@@ -1,4 +1,4 @@
-import { randomBytes, randomUUID, createHash } from "node:crypto";
+import { randomBytes, randomUUID } from "node:crypto";
 import type { Response } from "express";
 import type {
   OAuthServerProvider,
@@ -11,15 +11,15 @@ import type {
   OAuthTokens,
   OAuthTokenRevocationRequest,
 } from "@modelcontextprotocol/sdk/shared/auth.js";
+import type { KVStore } from "./kv-store.js";
 
-// --- In-memory stores ---
+// --- Stored value shapes ---
 
 interface PendingAuth {
   clientId: string;
   redirectUri: string;
   state?: string;
   codeChallenge: string;
-  createdAt: number;
 }
 
 interface AuthCode {
@@ -30,33 +30,41 @@ interface AuthCode {
   codeChallenge: string;
   redirectUri: string;
   clientId: string;
-  createdAt: number;
 }
 
-const TTL_MS = 10 * 60 * 1000; // 10 minutes
+// --- Redis key namespacing + TTLs ---
 
-export class OpseeClientStore implements OAuthRegisteredClientsStore {
-  private clients = new Map<string, OAuthClientInformationFull>();
+const CLIENT_KEY = (id: string) => `oauth:client:${id}`;
+const PENDING_KEY = (id: string) => `oauth:pending:${id}`;
+const CODE_KEY = (code: string) => `oauth:code:${code}`;
+const REVOKED_KEY = (token: string) => `oauth:revoked:${token}`;
 
-  getClient(clientId: string): OAuthClientInformationFull | undefined {
-    const known = this.clients.get(clientId);
-    if (known) return known;
+const FLOW_TTL_SECONDS = 10 * 60; // pending auths + auth codes: 10 minutes
+const CLIENT_TTL_SECONDS = 30 * 24 * 60 * 60; // dynamic client registrations: 30 days
+const REVOKED_FALLBACK_TTL_SECONDS = 24 * 60 * 60; // if token expiry is unknown
 
-    // Accept any client ID - required for stateless multi-replica deployments
-    // where registration may have happened on a different pod.
-    // The OAuth flow itself (PKCE + auth code) provides the security.
-    return {
-      client_id: clientId,
-      redirect_uris: [],
-      token_endpoint_auth_method: "none",
-      grant_types: ["authorization_code"],
-      response_types: ["code"],
-    } as unknown as OAuthClientInformationFull;
+export class OpseeClientStore implements OAuthRegisteredClientsStore {
+  constructor(private readonly store: KVStore) {}
+
+  async getClient(
+    clientId: string,
+  ): Promise<OAuthClientInformationFull | undefined> {
+    const raw = await this.store.get(CLIENT_KEY(clientId));
+    if (!raw) {
+      // Unknown client. With a shared Redis store this means the client was
+      // never registered (or its registration expired) — return undefined so
+      // the SDK responds with invalid_client and the MCP client re-registers
+      // via Dynamic Client Registration. (Previously we returned a synthetic
+      // client with an empty redirect_uris list, which made the SDK reject
+      // every redirect_uri with "Unregistered redirect_uri".)
+      return undefined;
+    }
+    return JSON.parse(raw) as OAuthClientInformationFull;
   }
 
-  registerClient(
+  async registerClient(
     client: Omit<OAuthClientInformationFull, "client_id" | "client_id_issued_at">,
-  ): OAuthClientInformationFull {
+  ): Promise<OAuthClientInformationFull> {
     const clientId = randomUUID();
     const clientSecret = randomBytes(32).toString("hex");
     const registered: OAuthClientInformationFull = {
@@ -65,22 +73,25 @@ export class OpseeClientStore implements OAuthRegisteredClientsStore {
       client_secret: clientSecret,
       client_id_issued_at: Math.floor(Date.now() / 1000),
     };
-    this.clients.set(clientId, registered);
+    await this.store.set(
+      CLIENT_KEY(clientId),
+      JSON.stringify(registered),
+      CLIENT_TTL_SECONDS,
+    );
     return registered;
   }
 }
 
 export class OpseeOAuthProvider implements OAuthServerProvider {
-  private _clientsStore = new OpseeClientStore();
-  private pendingAuths = new Map<string, PendingAuth>();
-  private authCodes = new Map<string, AuthCode>();
-  private revokedTokens = new Set<string>();
-
+  private _clientsStore: OpseeClientStore;
+  private store: KVStore;
   private serverUrl: string;
   private appUrl: string;
 
-  constructor(serverUrl: string, appUrl?: string) {
+  constructor(serverUrl: string, store: KVStore, appUrl?: string) {
     this.serverUrl = serverUrl;
+    this.store = store;
+    this._clientsStore = new OpseeClientStore(store);
     this.appUrl = appUrl || process.env.OPSEE_APP_URL || "https://opsee.ai";
   }
 
@@ -98,13 +109,17 @@ export class OpseeOAuthProvider implements OAuthServerProvider {
   ): Promise<void> {
     const pendingId = randomBytes(16).toString("hex");
 
-    this.pendingAuths.set(pendingId, {
+    const pending: PendingAuth = {
       clientId: client.client_id,
       redirectUri: params.redirectUri,
       state: params.state,
       codeChallenge: params.codeChallenge,
-      createdAt: Date.now(),
-    });
+    };
+    await this.store.set(
+      PENDING_KEY(pendingId),
+      JSON.stringify(pending),
+      FLOW_TTL_SECONDS,
+    );
 
     // Build callback URL back to our server
     const callbackUrl = `${this.serverUrl}/oauth/callback?pending=${pendingId}`;
@@ -120,9 +135,9 @@ export class OpseeOAuthProvider implements OAuthServerProvider {
     _client: OAuthClientInformationFull,
     authorizationCode: string,
   ): Promise<string> {
-    const code = this.authCodes.get(authorizationCode);
-    if (!code) throw new Error("Invalid authorization code");
-    return code.codeChallenge;
+    const raw = await this.store.get(CODE_KEY(authorizationCode));
+    if (!raw) throw new Error("Invalid authorization code");
+    return (JSON.parse(raw) as AuthCode).codeChallenge;
   }
 
   /**
@@ -132,16 +147,13 @@ export class OpseeOAuthProvider implements OAuthServerProvider {
     _client: OAuthClientInformationFull,
     authorizationCode: string,
   ): Promise<OAuthTokens> {
-    const code = this.authCodes.get(authorizationCode);
-    if (!code) throw new Error("Invalid or expired authorization code");
-
-    if (Date.now() - code.createdAt > TTL_MS) {
-      this.authCodes.delete(authorizationCode);
-      throw new Error("Authorization code expired");
-    }
+    const raw = await this.store.get(CODE_KEY(authorizationCode));
+    if (!raw) throw new Error("Invalid or expired authorization code");
 
     // One-time use
-    this.authCodes.delete(authorizationCode);
+    await this.store.del(CODE_KEY(authorizationCode));
+
+    const code = JSON.parse(raw) as AuthCode;
 
     // Calculate expires_in from the JWT's expiresAt
     let expiresIn: number | undefined;
@@ -166,7 +178,7 @@ export class OpseeOAuthProvider implements OAuthServerProvider {
    * We do lightweight validation here; the backend does full validation on API calls.
    */
   async verifyAccessToken(token: string): Promise<AuthInfo> {
-    if (this.revokedTokens.has(token)) {
+    if (await this.store.get(REVOKED_KEY(token))) {
       throw new Error("Token has been revoked");
     }
 
@@ -205,7 +217,24 @@ export class OpseeOAuthProvider implements OAuthServerProvider {
     _client: OAuthClientInformationFull,
     request: OAuthTokenRevocationRequest,
   ): Promise<void> {
-    this.revokedTokens.add(request.token);
+    // Keep the revocation marker only as long as the token could still be
+    // valid. Derive that from the JWT's exp when available.
+    let ttl = REVOKED_FALLBACK_TTL_SECONDS;
+    const parts = request.token.split(".");
+    if (parts.length === 3) {
+      try {
+        const payload = JSON.parse(
+          Buffer.from(parts[1], "base64url").toString("utf-8"),
+        );
+        if (payload.exp) {
+          const remaining = payload.exp - Math.floor(Date.now() / 1000);
+          if (remaining > 0) ttl = remaining;
+        }
+      } catch {
+        // Fall back to default TTL on undecodable tokens.
+      }
+    }
+    await this.store.set(REVOKED_KEY(request.token), "1", ttl);
   }
 
   // --- Custom methods for the callback flow ---
@@ -214,27 +243,24 @@ export class OpseeOAuthProvider implements OAuthServerProvider {
    * Step 2: Opsee login redirects back to /oauth/callback.
    * We generate an auth code and redirect to Claude's redirect_uri.
    */
-  handleCallback(
+  async handleCallback(
     pendingId: string,
     token: string,
     userId: string,
     companyId: string,
     expiresAt: string,
-  ): { redirectUri: string } | { error: string } {
-    const pending = this.pendingAuths.get(pendingId);
-    if (!pending) return { error: "Invalid or expired pending authorization" };
-
-    if (Date.now() - pending.createdAt > TTL_MS) {
-      this.pendingAuths.delete(pendingId);
-      return { error: "Pending authorization expired" };
-    }
+  ): Promise<{ redirectUri: string } | { error: string }> {
+    const raw = await this.store.get(PENDING_KEY(pendingId));
+    if (!raw) return { error: "Invalid or expired pending authorization" };
 
     // One-time use
-    this.pendingAuths.delete(pendingId);
+    await this.store.del(PENDING_KEY(pendingId));
+
+    const pending = JSON.parse(raw) as PendingAuth;
 
     // Generate authorization code
     const authCode = randomBytes(32).toString("hex");
-    this.authCodes.set(authCode, {
+    const code: AuthCode = {
       token,
       userId,
       companyId,
@@ -242,8 +268,8 @@ export class OpseeOAuthProvider implements OAuthServerProvider {
       codeChallenge: pending.codeChallenge,
       redirectUri: pending.redirectUri,
       clientId: pending.clientId,
-      createdAt: Date.now(),
-    });
+    };
+    await this.store.set(CODE_KEY(authCode), JSON.stringify(code), FLOW_TTL_SECONDS);
 
     // Build redirect URL with code and state
     const url = new URL(pending.redirectUri);
@@ -252,15 +278,4 @@ export class OpseeOAuthProvider implements OAuthServerProvider {
 
     return { redirectUri: url.toString() };
   }
-
-  /** Periodic cleanup of expired entries */
-  cleanup(): void {
-    const now = Date.now();
-    for (const [id, entry] of this.pendingAuths) {
-      if (now - entry.createdAt > TTL_MS) this.pendingAuths.delete(id);
-    }
-    for (const [code, entry] of this.authCodes) {
-      if (now - entry.createdAt > TTL_MS) this.authCodes.delete(code);
-    }
-  }
 }

package/src/client/api.ts

@@ -36,6 +36,10 @@ const authInterceptor: Interceptor = (next) => async (req) => {
   if (token) {
     req.header.set("Authorization", `Bearer ${token}`);
   }
+  // Mark this as an automation (MCP) client so the backend stamps live board
+  // events with the system actor — an agent acting under a user's token must
+  // not be self-skipped on that user's own board. (ADR-0002 §5; Slice 5.)
+  req.header.set("X-Opsee-Client", "mcp");
   return await next(req);
 };
 

package/src/server-http.ts

@@ -6,6 +6,7 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 import { mcpAuthRouter, getOAuthProtectedResourceMetadataUrl } from "@modelcontextprotocol/sdk/server/auth/router.js";
 import { requireBearerAuth } from "@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js";
 import { OpseeOAuthProvider } from "./auth/oauth-provider.js";
+import { createKVStore } from "./auth/kv-store.js";
 import { tokenContext } from "./auth/token-context.js";
 import { createServer } from "./server.js";
 
@@ -28,12 +29,10 @@ export async function startHttpServer(): Promise<void> {
   const backendUrl =
     process.env.OPSEE_API_URL || "https://grpc.api.opsee.ai";
 
-  const provider = new OpseeOAuthProvider(serverUrl);
+  const store = createKVStore();
+  const provider = new OpseeOAuthProvider(serverUrl, store);
   const issuerUrl = new URL(serverUrl);
 
-  // Periodically clean up expired auth entries
-  setInterval(() => provider.cleanup(), 60_000);
-
   const app = express();
   // Trust proxy headers (X-Forwarded-For) from nginx ingress
   app.set("trust proxy", 1);
@@ -57,7 +56,7 @@ export async function startHttpServer(): Promise<void> {
   );
 
   // --- Custom OAuth callback (Opsee login redirects here) ---
-  app.get("/oauth/callback", (req, res) => {
+  app.get("/oauth/callback", async (req, res) => {
     const { pending, token, userId, companyId, expiresAt } = req.query as Record<string, string>;
 
     if (!pending || !token) {
@@ -65,7 +64,7 @@ export async function startHttpServer(): Promise<void> {
       return;
     }
 
-    const result = provider.handleCallback(
+    const result = await provider.handleCallback(
       pending,
       token,
       userId || "",