@opsee/mcp-server 0.9.56 → 0.9.58

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opsee/mcp-server",
-  "version": "0.9.56",
+  "version": "0.9.58",
   "description": "Opsee MCP server — manage projects, tasks, docs, and cycles from AI coding environments",
   "type": "module",
   "bin": {

package/src/auth/oauth-provider.ts

@@ -11,7 +11,12 @@ import type {
   OAuthTokens,
   OAuthTokenRevocationRequest,
 } from "@modelcontextprotocol/sdk/shared/auth.js";
+import {
+  InvalidGrantError,
+  InvalidTokenError,
+} from "@modelcontextprotocol/sdk/server/auth/errors.js";
 import type { KVStore } from "./kv-store.js";
+import { renewAccessToken, type TokenRenewer } from "./renew.js";
 
 // --- Stored value shapes ---
 
@@ -32,15 +37,41 @@ interface AuthCode {
   clientId: string;
 }
 
+/** Server-side record behind an opaque refresh token. */
+interface RefreshRecord {
+  /** The last access token issued to this session. Used to mint the next one. */
+  accessToken: string;
+  userId: string;
+  companyId: string;
+  clientId: string;
+}
+
 // --- Redis key namespacing + TTLs ---
 
 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}`;
+const REFRESH_KEY = (token: string) => `oauth:refresh:${token}`;
 
 const FLOW_TTL_SECONDS = 10 * 60; // pending auths + auth codes: 10 minutes
 const REVOKED_FALLBACK_TTL_SECONDS = 24 * 60 * 60; // if token expiry is unknown
+// Refresh tokens outlive the access token they renew, so a client that has been
+// idle for longer than one access-token lifetime can still come back without
+// sending the user through an interactive login.
+const REFRESH_TTL_SECONDS = 180 * 24 * 60 * 60; // 180 days
+
+/**
+ * Converts an RFC3339 expiry into the `expires_in` seconds an OAuth token
+ * response carries. Returns undefined when the expiry is absent or unparseable
+ * so the field is simply omitted rather than reported as an immediate expiry.
+ */
+function expiresInFrom(expiresAt: string): number | undefined {
+  if (!expiresAt) return undefined;
+  const expMs = new Date(expiresAt).getTime();
+  if (Number.isNaN(expMs)) return undefined;
+  return Math.max(0, Math.floor((expMs - Date.now()) / 1000));
+}
 
 export class OpseeClientStore implements OAuthRegisteredClientsStore {
   constructor(private readonly store: KVStore) {}
@@ -94,12 +125,19 @@ export class OpseeOAuthProvider implements OAuthServerProvider {
   private store: KVStore;
   private serverUrl: string;
   private appUrl: string;
-
-  constructor(serverUrl: string, store: KVStore, appUrl?: string) {
+  private renew: TokenRenewer;
+
+  constructor(
+    serverUrl: string,
+    store: KVStore,
+    appUrl?: string,
+    renew: TokenRenewer = renewAccessToken,
+  ) {
     this.serverUrl = serverUrl;
     this.store = store;
     this._clientsStore = new OpseeClientStore(store);
     this.appUrl = appUrl || process.env.OPSEE_APP_URL || "https://opsee.ai";
+    this.renew = renew;
   }
 
   get clientsStore(): OAuthRegisteredClientsStore {
@@ -162,22 +200,87 @@ export class OpseeOAuthProvider implements OAuthServerProvider {
 
     const code = JSON.parse(raw) as AuthCode;
 
-    // Calculate expires_in from the JWT's expiresAt
-    let expiresIn: number | undefined;
-    if (code.expiresAt) {
-      const expMs = new Date(code.expiresAt).getTime() - Date.now();
-      expiresIn = Math.max(0, Math.floor(expMs / 1000));
-    }
-
     return {
       access_token: code.token,
       token_type: "bearer",
-      expires_in: expiresIn,
+      expires_in: expiresInFrom(code.expiresAt),
+      // Without a refresh token the client has exactly one credential: any
+      // failure to present it — expiry, revocation, a transient 5xx — can only
+      // be recovered by sending the user through an interactive login again.
+      refresh_token: await this.issueRefreshToken({
+        accessToken: code.token,
+        userId: code.userId,
+        companyId: code.companyId,
+        clientId: code.clientId,
+      }),
     };
   }
 
-  async exchangeRefreshToken(): Promise<OAuthTokens> {
-    throw new Error("Refresh tokens are not supported. Re-authenticate to get a new token.");
+  /**
+   * Mints an opaque refresh token for a session and persists the record it
+   * stands for. Refresh tokens are rotated on every use, so each call replaces
+   * the previous handle.
+   */
+  private async issueRefreshToken(record: RefreshRecord): Promise<string> {
+    const refreshToken = randomBytes(32).toString("hex");
+    await this.store.set(
+      REFRESH_KEY(refreshToken),
+      JSON.stringify(record),
+      REFRESH_TTL_SECONDS,
+    );
+    return refreshToken;
+  }
+
+  /**
+   * Trades a refresh token for a freshly minted access token.
+   *
+   * The stored access token is used to authenticate the renewal against the
+   * backend, so the session rolls forward for as long as the client keeps
+   * refreshing — the user is only sent back through the login UI once the
+   * stored token has itself lapsed.
+   */
+  async exchangeRefreshToken(
+    client: OAuthClientInformationFull,
+    refreshToken: string,
+  ): Promise<OAuthTokens> {
+    const raw = await this.store.get(REFRESH_KEY(refreshToken));
+    if (!raw) throw new InvalidGrantError("Invalid or expired refresh token");
+
+    const record = JSON.parse(raw) as RefreshRecord;
+
+    // A refresh token belongs to the client it was issued to. Without this a
+    // leaked handle could be redeemed by any other registered client.
+    if (record.clientId !== client.client_id) {
+      throw new InvalidGrantError("Refresh token was issued to another client");
+    }
+
+    // Rotate: the presented handle is spent whether or not renewal succeeds, so
+    // a captured refresh token cannot be replayed.
+    await this.store.del(REFRESH_KEY(refreshToken));
+
+    let renewed;
+    try {
+      renewed = await this.renew(record.accessToken);
+    } catch (err) {
+      // The stored token is no longer good enough to mint another (expired,
+      // user deactivated, backend rejecting it). Surface invalid_grant so the
+      // client falls back to a full authorization instead of retrying forever.
+      throw new InvalidGrantError(
+        `Could not renew the session: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+
+    return {
+      access_token: renewed.token,
+      token_type: "bearer",
+      expires_in: expiresInFrom(renewed.expiresAt),
+      refresh_token: await this.issueRefreshToken({
+        accessToken: renewed.token,
+        userId: renewed.userId || record.userId,
+        companyId: renewed.companyId || record.companyId,
+        clientId: record.clientId,
+      }),
+    };
   }
 
   /**
@@ -185,13 +288,13 @@ 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 (await this.store.get(REVOKED_KEY(token))) {
-      throw new Error("Token has been revoked");
+    if (await this.isRevoked(token)) {
+      throw new InvalidTokenError("Token has been revoked");
     }
 
     // Decode JWT payload without crypto verification
     const parts = token.split(".");
-    if (parts.length !== 3) throw new Error("Invalid token format");
+    if (parts.length !== 3) throw new InvalidTokenError("Invalid token format");
 
     // Scope the try to ONLY the decode/parse: a malformed payload becomes
     // "Invalid token". The validation checks below run outside the catch so
@@ -201,16 +304,16 @@ export class OpseeOAuthProvider implements OAuthServerProvider {
     try {
       payload = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf-8"));
     } catch {
-      throw new Error("Invalid token");
+      throw new InvalidTokenError("Invalid token");
     }
 
     // Require an expiry claim and reject expired tokens. A token that omits
     // exp must not be treated as valid indefinitely.
     if (typeof payload.exp !== "number") {
-      throw new Error("Token missing expiry");
+      throw new InvalidTokenError("Token missing expiry");
     }
     if (payload.exp < Math.floor(Date.now() / 1000)) {
-      throw new Error("Token expired");
+      throw new InvalidTokenError("Token expired");
     }
 
     return {
@@ -226,10 +329,40 @@ export class OpseeOAuthProvider implements OAuthServerProvider {
     };
   }
 
+  /**
+   * Checks the revocation denylist, treating an unreachable store as "not
+   * revoked".
+   *
+   * This lookup runs on every authenticated request. Letting a store error
+   * propagate would turn a momentary Redis hiccup — a failover, a reconnect, a
+   * command timeout — into a failed request for every live session at once,
+   * and with no way for a client to tell that apart from a real credential
+   * problem, the user ends up re-authenticating by hand. Revocation is a
+   * best-effort denylist on top of a token that is already time-bounded and
+   * re-validated by the backend on every API call, so a read failure degrades
+   * to the pre-revocation behaviour rather than locking everyone out.
+   */
+  private async isRevoked(token: string): Promise<boolean> {
+    try {
+      return (await this.store.get(REVOKED_KEY(token))) !== null;
+    } catch (err) {
+      console.error(
+        "[oauth] revocation check unavailable, allowing token:",
+        err instanceof Error ? err.message : err,
+      );
+      return false;
+    }
+  }
+
   async revokeToken(
     _client: OAuthClientInformationFull,
     request: OAuthTokenRevocationRequest,
   ): Promise<void> {
+    // A refresh handle is opaque, not a JWT — drop the record outright so it
+    // cannot be redeemed, rather than filing it on the JWT denylist where
+    // verifyAccessToken would never look it up.
+    await this.store.del(REFRESH_KEY(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;

package/src/auth/renew.ts

@@ -0,0 +1,56 @@
+import { createClient } from "@connectrpc/connect";
+import { createConnectTransport } from "@connectrpc/connect-node";
+import { AccountService } from "../../gen/api/v1/account_pb.js";
+
+/**
+ * A freshly minted MCP access token plus the identity it belongs to.
+ */
+export interface RenewedToken {
+  token: string;
+  userId: string;
+  companyId: string;
+  /** RFC3339 expiry, as returned by the backend. Empty when unknown. */
+  expiresAt: string;
+}
+
+/**
+ * Mints a new MCP access token on behalf of the holder of `currentToken`.
+ *
+ * `GenerateMCPToken` authenticates the caller from the bearer token itself, so
+ * a still-valid token is all that is needed to roll a new one — no user
+ * interaction and no signing key on this side. That is what lets a refresh
+ * token renew a session: we keep the last good access token server-side and
+ * trade it for a fresh one, rather than handing the same token back forever.
+ */
+export type TokenRenewer = (currentToken: string) => Promise<RenewedToken>;
+
+function backendUrl(): string {
+  return process.env.OPSEE_API_URL || "https://grpc.api.opsee.ai";
+}
+
+export const renewAccessToken: TokenRenewer = async (currentToken) => {
+  // Built per call rather than cached: the bearer differs for every renewal,
+  // and renewals are rare enough that connection reuse is not worth the risk
+  // of leaking one user's token onto another user's request.
+  const transport = createConnectTransport({
+    baseUrl: backendUrl(),
+    httpVersion: "1.1",
+    interceptors: [
+      (next) => async (req) => {
+        req.header.set("Authorization", `Bearer ${currentToken}`);
+        req.header.set("X-Opsee-Client", "mcp");
+        return await next(req);
+      },
+    ],
+  });
+
+  const account = createClient(AccountService, transport);
+  const res = await account.generateMCPToken({});
+
+  return {
+    token: res.token,
+    userId: res.userId,
+    companyId: res.companyId,
+    expiresAt: res.expiresAt,
+  };
+};