@eraserlabs/eraser-mcp 0.7.0 → 0.8.0

package/README.md

@@ -4,33 +4,41 @@ Model Context Protocol (MCP) server for [Eraser](https://eraser.io) - generate d
 
 ## Quick Start
 
-```bash
-npx @eraserlabs/eraser-mcp
+**Remote MCP endpoint:** `https://app.eraser.io/api/mcp`
+
+Add this to your MCP config (e.g. **Cursor:** `.cursor/mcp.json` · **Claude Desktop:** your app's MCP settings file):
+
+```json
+{
+  "mcpServers": {
+    "eraser": {
+      "type": "http",
+      "url": "https://app.eraser.io/api/mcp"
+    }
+  }
+}
 ```
 
-## Configuration
+Your client will prompt you to sign in to Eraser when authentication is required.
 
-### Cursor
+### npx (stdio bridge + OAuth)
 
-Add to `.cursor/mcp.json`:
+Use the published npm package when you want a **local stdio** MCP server. It proxies to the same remote endpoint and signs you in with **OAuth** on first run (browser opens; credentials are stored on your machine).
+
+Add this to your MCP config:
 
 ```json
 {
   "mcpServers": {
     "eraser": {
       "command": "npx",
-      "args": ["@eraserlabs/eraser-mcp"],
-      "env": {
-        "ERASER_API_TOKEN": "your-api-token"
-      }
+      "args": ["@eraserlabs/eraser-mcp"]
     }
   }
 }
 ```
 
-### Claude Desktop
-
-Add to your Claude Desktop config:
+**API token (optional):** To skip OAuth (e.g. CI, scripts, or headless environments), add `ERASER_API_TOKEN` to `env` with an [API token from Eraser Settings](https://app.eraser.io/settings/api-tokens):
 
 ```json
 {
@@ -46,65 +54,89 @@ Add to your Claude Desktop config:
 }
 ```
 
+## CLI Commands
+
+| Command                             | Description                                         |
+| ----------------------------------- | --------------------------------------------------- |
+| `npx @eraserlabs/eraser-mcp`        | Start the MCP server (auto-authenticates via OAuth) |
+| `npx @eraserlabs/eraser-mcp login`  | Manually trigger login                              |
+| `npx @eraserlabs/eraser-mcp logout` | Clear saved credentials                             |
+| `npx @eraserlabs/eraser-mcp whoami` | Show current auth status                            |
+
 ## Environment Variables
 
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `ERASER_API_TOKEN` | Yes | Your Eraser API token |
-| `ERASER_API_URL` | No | Custom API URL (default: `https://app.eraser.io/api/mcp`) |
-| `ERASER_OUTPUT_DIR` | No | Directory to save rendered diagrams (default: `.eraser/scratchpad`) |
+| Variable            | Required | Description                                                                                               |
+| ------------------- | -------- | --------------------------------------------------------------------------------------------------------- |
+| `ERASER_API_TOKEN`  | No       | API token for CI/CD and headless environments (skips OAuth flow)                                          |
+| `ERASER_API_URL`    | No       | MCP HTTP endpoint (default: production `https://app.eraser.io/api/mcp`; set only for staging/self-hosted) |
+| `ERASER_OUTPUT_DIR` | No       | Directory to save rendered diagrams (default: `.eraser/scratchpad`)                                       |
+
+## CI/CD and Headless Environments
+
+For automated pipelines where a browser login isn't possible, set the `ERASER_API_TOKEN` environment variable. The OAuth flow is skipped entirely and the token is passed directly to the Eraser API.
+
+Get your API token from [Eraser Settings](https://app.eraser.io/settings/api-tokens). Use the same config block shown in [API token (optional)](#npx-stdio-bridge--oauth) above.
 
 ## Available Tools
 
+### Identity
+
+Call `whoami` first to get the current user and active team.
+
+| Tool         | Description                                                                                      |
+| ------------ | ------------------------------------------------------------------------------------------------ |
+| `whoami`     | Returns current user profile, active team, and list of all teams. **Call this first.**          |
+| `listTeams`  | Lists all teams the user is a member of (usually not needed since `whoami` includes this)       |
+| `selectTeam` | Selects which team to use for subsequent operations when the user has multiple teams            |
+
 ### AI Diagram
 
 Prompt to diagram.
 
-| Tool | Description |
-|------|-------------|
+| Tool           | Description                                      |
+| -------------- | ------------------------------------------------ |
 | `renderPrompt` | Generate diagrams from natural language using AI |
 
 ### Rendering
 
 Diagram code (DSL) to diagram.
 
-| Tool | Description |
-|------|-------------|
-| `renderSequenceDiagram` | Render sequence diagrams from diagram code |
-| `renderEntityRelationshipDiagram` | Render ERD diagrams from diagram code |
-| `renderCloudArchitectureDiagram` | Render cloud architecture diagrams from diagram code |
-| `renderFlowchart` | Render flowcharts from diagram code |
-| `renderBpmnDiagram` | Render BPMN diagrams from diagram code |
-| `renderElements` | Render multiple diagram elements from diagram code |
+| Tool                              | Description                                          |
+| --------------------------------- | ---------------------------------------------------- |
+| `renderSequenceDiagram`           | Render sequence diagrams from diagram code           |
+| `renderEntityRelationshipDiagram` | Render ERD diagrams from diagram code                |
+| `renderCloudArchitectureDiagram`  | Render cloud architecture diagrams from diagram code |
+| `renderFlowchart`                 | Render flowcharts from diagram code                  |
+| `renderBpmnDiagram`               | Render BPMN diagrams from diagram code               |
+| `renderElements`                  | Render multiple diagram elements from diagram code   |
 
 ### Files
 
 CRUD for files on app.eraser.io.
 
-| Tool | Description |
-|------|-------------|
-| `createFile` | Create a new Eraser file with document and/or diagram elements |
-| `listFiles` | List files in the workspace with pagination, sorting, and filtering |
-| `getFile` | Get a single file including metadata, content, and diagram elements |
-| `updateFile` | Update an existing file's metadata and/or document content |
-| `archiveFile` | Archive (soft-delete) a file |
+| Tool          | Description                                                         |
+| ------------- | ------------------------------------------------------------------- |
+| `createFile`  | Create a new Eraser file with document and/or diagram elements      |
+| `listFiles`   | List files in the workspace with pagination, sorting, and filtering |
+| `getFile`     | Get a single file including metadata, content, and diagram elements |
+| `updateFile`  | Update an existing file's metadata and/or document content          |
+| `archiveFile` | Archive (soft-delete) a file                                        |
 
 ### Diagrams
 
 CRUD for diagrams on app.eraser.io.
 
-| Tool | Description |
-|------|-------------|
-| `listDiagrams` | List all diagrams in a file |
+| Tool            | Description                              |
+| --------------- | ---------------------------------------- |
+| `listDiagrams`  | List all diagrams in a file              |
 | `createDiagram` | Create a new diagram in an existing file |
-| `getDiagram` | Get a specific diagram from a file |
-| `updateDiagram` | Update the code of an existing diagram |
+| `getDiagram`    | Get a specific diagram from a file       |
+| `updateDiagram` | Update the code of an existing diagram   |
 | `deleteDiagram` | Permanently delete a diagram from a file |
 
 ## Documentation
 
 - [Eraser Agent Integration Documentation](https://docs.eraser.io/docs/using-ai-agent-integrations)
-- [Get an API Token](https://docs.eraser.io/reference/api-token)
 
 ## License
 

package/dist/oauth/callback-server.d.ts

@@ -0,0 +1,6 @@
+export interface CallbackResult {
+    code: string;
+    state: string;
+}
+export declare function startCallbackServer(expectedState: string): Promise<CallbackResult>;
+//# sourceMappingURL=callback-server.d.ts.map

package/dist/oauth/callback-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"callback-server.d.ts","sourceRoot":"","sources":["../../src/oauth/callback-server.ts"],"names":[],"mappings":"AA2FA,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CA0ElF"}

package/dist/oauth/callback-server.js

@@ -0,0 +1,187 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startCallbackServer = startCallbackServer;
+const http = __importStar(require("http"));
+const url_1 = require("url");
+const config_1 = require("./config");
+/** Escape user-controlled OAuth error strings before embedding in HTML. */
+function escapeHtml(text) {
+    return text
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+const SUCCESS_HTML = `
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Eraser MCP - Authorization Complete</title>
+  <style>
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      display: flex;
+      justify-content: center;
+      align-items: center;
+      height: 100vh;
+      margin: 0;
+      background: #f6f6f6;
+    }
+    .container {
+      text-align: center;
+      padding: 40px;
+      background: white;
+      border-radius: 8px;
+      box-shadow: 0 2px 10px rgba(0,0,0,0.1);
+    }
+    h1 { color: #2a2b2b; margin-bottom: 16px; }
+    p { color: #666; }
+    .checkmark { font-size: 48px; margin-bottom: 16px; }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <div class="checkmark">✓</div>
+    <h1>Authorization Complete</h1>
+    <p>You can close this window and return to your terminal.</p>
+  </div>
+</body>
+</html>
+`;
+const ERROR_HTML = (rawMessage) => {
+    const message = escapeHtml(rawMessage);
+    return `
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Eraser MCP - Authorization Failed</title>
+  <style>
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      display: flex;
+      justify-content: center;
+      align-items: center;
+      height: 100vh;
+      margin: 0;
+      background: #f6f6f6;
+    }
+    .container {
+      text-align: center;
+      padding: 40px;
+      background: white;
+      border-radius: 8px;
+      box-shadow: 0 2px 10px rgba(0,0,0,0.1);
+    }
+    h1 { color: #e72f6e; margin-bottom: 16px; }
+    p { color: #666; }
+    .error-icon { font-size: 48px; margin-bottom: 16px; }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <div class="error-icon">✗</div>
+    <h1>Authorization Failed</h1>
+    <p>${message}</p>
+  </div>
+</body>
+</html>
+`;
+};
+function startCallbackServer(expectedState) {
+    return new Promise((resolve, reject) => {
+        let timeoutHandle = null;
+        const cleanup = () => {
+            if (timeoutHandle) {
+                clearTimeout(timeoutHandle);
+                timeoutHandle = null;
+            }
+        };
+        const server = http.createServer((req, res) => {
+            const url = new url_1.URL(req.url || '/', `http://127.0.0.1:${config_1.CALLBACK_PORT}`);
+            if (url.pathname !== '/callback') {
+                res.writeHead(404);
+                res.end('Not found');
+                return;
+            }
+            const code = url.searchParams.get('code');
+            const state = url.searchParams.get('state');
+            const error = url.searchParams.get('error');
+            const errorDescription = url.searchParams.get('error_description');
+            if (error) {
+                res.writeHead(400, { 'Content-Type': 'text/html' });
+                res.end(ERROR_HTML(errorDescription || error));
+                server.close();
+                cleanup();
+                reject(new Error(errorDescription || error));
+                return;
+            }
+            if (!code) {
+                res.writeHead(400, { 'Content-Type': 'text/html' });
+                res.end(ERROR_HTML('Missing authorization code'));
+                server.close();
+                cleanup();
+                reject(new Error('Missing authorization code'));
+                return;
+            }
+            if (state !== expectedState) {
+                res.writeHead(400, { 'Content-Type': 'text/html' });
+                res.end(ERROR_HTML('Invalid state parameter'));
+                server.close();
+                cleanup();
+                reject(new Error('Invalid state parameter - possible CSRF attack'));
+                return;
+            }
+            res.writeHead(200, { 'Content-Type': 'text/html' });
+            res.end(SUCCESS_HTML);
+            server.close();
+            cleanup();
+            resolve({ code, state });
+        });
+        server.on('error', (err) => {
+            cleanup();
+            reject(new Error(`Failed to start callback server: ${err.message}`));
+        });
+        server.listen(config_1.CALLBACK_PORT, '127.0.0.1', () => {
+            // Server is listening
+        });
+        // Timeout after 5 minutes
+        timeoutHandle = setTimeout(() => {
+            server.close();
+            reject(new Error('Authorization timed out'));
+        }, 5 * 60 * 1000);
+    });
+}

package/dist/oauth/config.d.ts

@@ -0,0 +1,4 @@
+import type { OAuthConfig } from './types';
+export declare const DEFAULT_OAUTH_CONFIG: OAuthConfig;
+export declare const CALLBACK_PORT = 9876;
+//# sourceMappingURL=config.d.ts.map

package/dist/oauth/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/oauth/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAI3C,eAAO,MAAM,oBAAoB,EAAE,WAOlC,CAAC;AAEF,eAAO,MAAM,aAAa,OAAO,CAAC"}

package/dist/oauth/config.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CALLBACK_PORT = exports.DEFAULT_OAUTH_CONFIG = void 0;
+const BASE_URL = process.env.ERASER_API_URL?.replace('/api/mcp', '') || 'https://app.eraser.io';
+exports.DEFAULT_OAUTH_CONFIG = {
+    authorizationEndpoint: `${BASE_URL}/api/oauth/authorize`,
+    tokenEndpoint: `${BASE_URL}/api/oauth/token`,
+    clientId: 'eraser-mcp-cli',
+    redirectUri: 'http://127.0.0.1:9876/callback',
+    scopes: ['mcp:read', 'mcp:write', 'mcp:generate', 'mcp:render'],
+    resource: `${BASE_URL}/api/mcp`,
+};
+exports.CALLBACK_PORT = 9876;

package/dist/oauth/flow.d.ts

@@ -0,0 +1,17 @@
+import type { StoredCredentials } from './types';
+export declare function performLogin(): Promise<StoredCredentials>;
+export declare function ensureValidToken(): Promise<string>;
+/**
+ * After the API returns 401, try refresh_token before wiping credentials or
+ * opening the browser. Use this instead of invalidateCredentials() + ensureValidToken()
+ * so refresh_token in ~/.eraser/ is preserved until refresh actually fails.
+ */
+export declare function recoverAuthAfter401(): Promise<string>;
+/**
+ * Clears stored OAuth credentials (e.g. explicit logout). Prefer recoverAuthAfter401
+ * when the server returns 401 so refresh_token can be used first.
+ */
+export declare function invalidateCredentials(): void;
+export declare function logout(): void;
+export declare function whoami(): Promise<void>;
+//# sourceMappingURL=flow.d.ts.map

package/dist/oauth/flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow.d.ts","sourceRoot":"","sources":["../../src/oauth/flow.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,iBAAiB,EAAiB,MAAM,SAAS,CAAC;AA8EhE,wBAAsB,YAAY,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAwC/D;AAED,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC,CA6BxD;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,MAAM,CAAC,CAyB3D;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAED,wBAAgB,MAAM,IAAI,IAAI,CAG7B;AAED,wBAAsB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAgB5C"}

package/dist/oauth/flow.js

@@ -0,0 +1,222 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.performLogin = performLogin;
+exports.ensureValidToken = ensureValidToken;
+exports.recoverAuthAfter401 = recoverAuthAfter401;
+exports.invalidateCredentials = invalidateCredentials;
+exports.logout = logout;
+exports.whoami = whoami;
+const crypto = __importStar(require("crypto"));
+const config_1 = require("./config");
+const pkce_1 = require("./pkce");
+const callback_server_1 = require("./callback-server");
+const token_storage_1 = require("./token-storage");
+/** The API URL used for scoping stored credentials. */
+const CREDENTIAL_KEY = config_1.DEFAULT_OAUTH_CONFIG.resource;
+function openBrowser(url) {
+    const { exec } = require('child_process');
+    const platform = process.platform;
+    let command;
+    if (platform === 'darwin') {
+        command = `open "${url}"`;
+    }
+    else if (platform === 'win32') {
+        command = `start "" "${url}"`;
+    }
+    else {
+        command = `xdg-open "${url}"`;
+    }
+    exec(command, (err) => {
+        if (err) {
+            console.error(`Failed to open browser: ${err.message}`);
+            console.error(`Please open this URL manually:\n${url}`);
+        }
+    });
+}
+async function exchangeCodeForTokens(code, codeVerifier) {
+    const body = new URLSearchParams({
+        grant_type: 'authorization_code',
+        code,
+        code_verifier: codeVerifier,
+        client_id: config_1.DEFAULT_OAUTH_CONFIG.clientId,
+        redirect_uri: config_1.DEFAULT_OAUTH_CONFIG.redirectUri,
+        resource: config_1.DEFAULT_OAUTH_CONFIG.resource,
+    });
+    const response = await fetch(config_1.DEFAULT_OAUTH_CONFIG.tokenEndpoint, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/x-www-form-urlencoded',
+        },
+        body: body.toString(),
+    });
+    if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`Token exchange failed: ${response.status} ${text}`);
+    }
+    return (await response.json());
+}
+async function refreshAccessToken(refreshToken) {
+    const body = new URLSearchParams({
+        grant_type: 'refresh_token',
+        refresh_token: refreshToken,
+        client_id: config_1.DEFAULT_OAUTH_CONFIG.clientId,
+        resource: config_1.DEFAULT_OAUTH_CONFIG.resource,
+    });
+    const response = await fetch(config_1.DEFAULT_OAUTH_CONFIG.tokenEndpoint, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/x-www-form-urlencoded',
+        },
+        body: body.toString(),
+    });
+    if (!response.ok) {
+        throw new Error(`Token refresh failed: ${response.status}`);
+    }
+    return (await response.json());
+}
+async function performLogin() {
+    const { codeVerifier, codeChallenge } = (0, pkce_1.generatePKCE)();
+    const state = crypto.randomBytes(16).toString('hex');
+    const authUrl = new URL(config_1.DEFAULT_OAUTH_CONFIG.authorizationEndpoint);
+    authUrl.searchParams.set('response_type', 'code');
+    authUrl.searchParams.set('client_id', config_1.DEFAULT_OAUTH_CONFIG.clientId);
+    authUrl.searchParams.set('redirect_uri', config_1.DEFAULT_OAUTH_CONFIG.redirectUri);
+    authUrl.searchParams.set('code_challenge', codeChallenge);
+    authUrl.searchParams.set('code_challenge_method', 'S256');
+    authUrl.searchParams.set('scope', config_1.DEFAULT_OAUTH_CONFIG.scopes.join(' '));
+    authUrl.searchParams.set('resource', config_1.DEFAULT_OAUTH_CONFIG.resource);
+    authUrl.searchParams.set('state', state);
+    console.error(`Opening browser for authentication...`);
+    console.error(`If the browser doesn't open, visit:\n${authUrl.toString()}\n`);
+    // Start the callback server before opening the browser
+    const callbackPromise = (0, callback_server_1.startCallbackServer)(state);
+    // Open browser
+    openBrowser(authUrl.toString());
+    // Wait for callback
+    const { code } = await callbackPromise;
+    console.error('Exchanging authorization code for tokens...');
+    const tokens = await exchangeCodeForTokens(code, codeVerifier);
+    const credentials = {
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token,
+        expiresAt: Date.now() + tokens.expires_in * 1000,
+        scope: tokens.scope,
+    };
+    (0, token_storage_1.saveCredentials)(credentials, CREDENTIAL_KEY);
+    console.error('Login successful! Credentials saved.\n');
+    return credentials;
+}
+async function ensureValidToken() {
+    let credentials = (0, token_storage_1.loadCredentials)(CREDENTIAL_KEY);
+    if (!credentials) {
+        credentials = await performLogin();
+        return credentials.accessToken;
+    }
+    if ((0, token_storage_1.isTokenExpired)(credentials)) {
+        try {
+            console.error('Refreshing access token...');
+            const tokens = await refreshAccessToken(credentials.refreshToken);
+            credentials = {
+                accessToken: tokens.access_token,
+                refreshToken: tokens.refresh_token,
+                expiresAt: Date.now() + tokens.expires_in * 1000,
+                scope: tokens.scope,
+            };
+            (0, token_storage_1.saveCredentials)(credentials, CREDENTIAL_KEY);
+        }
+        catch {
+            console.error('Token refresh failed, initiating new login...');
+            (0, token_storage_1.clearCredentials)(CREDENTIAL_KEY);
+            credentials = await performLogin();
+        }
+    }
+    return credentials.accessToken;
+}
+/**
+ * After the API returns 401, try refresh_token before wiping credentials or
+ * opening the browser. Use this instead of invalidateCredentials() + ensureValidToken()
+ * so refresh_token in ~/.eraser/ is preserved until refresh actually fails.
+ */
+async function recoverAuthAfter401() {
+    const credentials = (0, token_storage_1.loadCredentials)(CREDENTIAL_KEY);
+    if (!credentials) {
+        const loggedIn = await performLogin();
+        return loggedIn.accessToken;
+    }
+    try {
+        console.error('Refreshing access token (server rejected previous access token)...');
+        const tokens = await refreshAccessToken(credentials.refreshToken);
+        const updated = {
+            accessToken: tokens.access_token,
+            refreshToken: tokens.refresh_token,
+            expiresAt: Date.now() + tokens.expires_in * 1000,
+            scope: tokens.scope,
+        };
+        (0, token_storage_1.saveCredentials)(updated, CREDENTIAL_KEY);
+        return updated.accessToken;
+    }
+    catch {
+        console.error('Token refresh failed after 401, clearing credentials and re-authenticating...');
+        (0, token_storage_1.clearCredentials)(CREDENTIAL_KEY);
+        const loggedIn = await performLogin();
+        return loggedIn.accessToken;
+    }
+}
+/**
+ * Clears stored OAuth credentials (e.g. explicit logout). Prefer recoverAuthAfter401
+ * when the server returns 401 so refresh_token can be used first.
+ */
+function invalidateCredentials() {
+    (0, token_storage_1.clearCredentials)(CREDENTIAL_KEY);
+}
+function logout() {
+    (0, token_storage_1.clearCredentials)(CREDENTIAL_KEY);
+    console.error('Logged out successfully.\n');
+}
+async function whoami() {
+    const credentials = (0, token_storage_1.loadCredentials)(CREDENTIAL_KEY);
+    if (!credentials) {
+        console.error('Not logged in. Run `eraser-mcp login` to authenticate.\n');
+        return;
+    }
+    if ((0, token_storage_1.isTokenExpired)(credentials)) {
+        console.error('Token expired. Run `eraser-mcp login` to re-authenticate.\n');
+        return;
+    }
+    console.error('Logged in to Eraser MCP.');
+    console.error(`Scopes: ${credentials.scope}`);
+    console.error(`Token expires: ${new Date(credentials.expiresAt).toLocaleString()}\n`);
+}

package/dist/oauth/index.d.ts

@@ -0,0 +1,7 @@
+export * from './types';
+export * from './config';
+export * from './pkce';
+export * from './token-storage';
+export * from './callback-server';
+export * from './flow';
+//# sourceMappingURL=index.d.ts.map

package/dist/oauth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/oauth/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,QAAQ,CAAC"}

package/dist/oauth/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./config"), exports);
+__exportStar(require("./pkce"), exports);
+__exportStar(require("./token-storage"), exports);
+__exportStar(require("./callback-server"), exports);
+__exportStar(require("./flow"), exports);