@orboto/mcp 0.178.0

package/dist/oauth-bootstrap.test.js

@@ -0,0 +1,212 @@
+/**
+ * ORB-943 - unit tests for the stdio OAuth bootstrap core. No browser, no
+ * network, no DB: a fake fetch drives discovery/register/exchange/refresh, and
+ * a temp file backs the cache. The interactive loopback shell is exercised via
+ * its testable pieces (PKCE, authorize-url, request builders).
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { mkdtempSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { generatePkce, buildAuthorizeUrl, deriveOrigin, discoverAuthServer, registerLoopbackClient, exchangeAuthCode, refreshTokens, loadCachedGrant, saveCachedGrant, clearCachedGrant, createTokenProvider, bootstrapOAuth, EXPIRY_SKEW_MS, } from './oauth-bootstrap.js';
+describe('PKCE', () => {
+    it('produces an S256 challenge that verifies against the verifier', () => {
+        const { verifier, challenge, method } = generatePkce();
+        expect(method).toBe('S256');
+        const recomputed = createHash('sha256').update(verifier).digest('base64url');
+        expect(recomputed).toBe(challenge);
+        // base64url, no padding
+        expect(challenge).not.toContain('=');
+        expect(challenge).not.toContain('+');
+    });
+});
+describe('deriveOrigin', () => {
+    it('strips a trailing /api (single-host reverse-proxy layout)', () => {
+        expect(deriveOrigin('https://orboto.example.com/api')).toBe('https://orboto.example.com');
+        expect(deriveOrigin('https://orboto.example.com/api/')).toBe('https://orboto.example.com');
+    });
+    it('leaves a bare origin unchanged', () => {
+        expect(deriveOrigin('http://localhost:3000')).toBe('http://localhost:3000');
+    });
+});
+describe('buildAuthorizeUrl', () => {
+    it('encodes all PKCE + client params', () => {
+        const url = new URL(buildAuthorizeUrl('https://x.test/oauth/authorize', {
+            clientId: 'cid', redirectUri: 'http://127.0.0.1:5555/callback', challenge: 'chal', state: 'st', scope: 'mcp offline_access',
+        }));
+        expect(url.searchParams.get('response_type')).toBe('code');
+        expect(url.searchParams.get('client_id')).toBe('cid');
+        expect(url.searchParams.get('redirect_uri')).toBe('http://127.0.0.1:5555/callback');
+        expect(url.searchParams.get('code_challenge')).toBe('chal');
+        expect(url.searchParams.get('code_challenge_method')).toBe('S256');
+        expect(url.searchParams.get('state')).toBe('st');
+        expect(url.searchParams.get('scope')).toBe('mcp offline_access');
+    });
+});
+function jsonResponse(body, status = 200) {
+    return new Response(JSON.stringify(body), { status, headers: { 'Content-Type': 'application/json' } });
+}
+describe('discovery / register / exchange / refresh', () => {
+    it('discoverAuthServer validates completeness', async () => {
+        const fetchImpl = vi.fn().mockResolvedValue(jsonResponse({
+            issuer: 'https://x.test',
+            authorization_endpoint: 'https://x.test/oauth/authorize',
+            token_endpoint: 'https://x.test/oauth/token',
+            registration_endpoint: 'https://x.test/oauth/register',
+        }));
+        const meta = await discoverAuthServer('https://x.test', fetchImpl);
+        expect(meta.token_endpoint).toBe('https://x.test/oauth/token');
+    });
+    it('discoverAuthServer throws on incomplete metadata', async () => {
+        const fetchImpl = vi.fn().mockResolvedValue(jsonResponse({ issuer: 'https://x.test' }));
+        await expect(discoverAuthServer('https://x.test', fetchImpl)).rejects.toThrow(/incomplete metadata/);
+    });
+    it('registerLoopbackClient returns the client_id', async () => {
+        const fetchImpl = vi.fn().mockResolvedValue(jsonResponse({ client_id: 'abc123' }, 201));
+        const id = await registerLoopbackClient('https://x.test/oauth/register', 'http://127.0.0.1:1/callback', fetchImpl);
+        expect(id).toBe('abc123');
+    });
+    it('exchangeAuthCode parses tokens + computes expiry', async () => {
+        const fetchImpl = vi.fn().mockResolvedValue(jsonResponse({
+            access_token: 'at', refresh_token: 'rt', expires_in: 3600, scope: 'mcp offline_access',
+        }));
+        const before = Date.now();
+        const tokens = await exchangeAuthCode('https://x.test/oauth/token', {
+            clientId: 'cid', code: 'code', redirectUri: 'http://127.0.0.1:1/callback', verifier: 'v',
+        }, fetchImpl);
+        expect(tokens.accessToken).toBe('at');
+        expect(tokens.refreshToken).toBe('rt');
+        expect(tokens.expiresAt).toBeGreaterThanOrEqual(before + 3600 * 1000);
+    });
+    it('refreshTokens surfaces a non-2xx as an error', async () => {
+        const fetchImpl = vi.fn().mockResolvedValue(new Response('{"error":"invalid_grant"}', { status: 400 }));
+        await expect(refreshTokens('https://x.test/oauth/token', { clientId: 'cid', refreshToken: 'rt' }, fetchImpl))
+            .rejects.toThrow(/refresh failed: 400/);
+    });
+});
+describe('token cache', () => {
+    let dir;
+    let path;
+    beforeEach(() => {
+        dir = mkdtempSync(join(tmpdir(), 'orboto-oauth-'));
+        path = join(dir, 'cache.json');
+    });
+    afterEach(() => rmSync(dir, { recursive: true, force: true }));
+    it('round-trips a grant keyed by origin and writes 0600', () => {
+        saveCachedGrant('https://a.test', { clientId: 'c', refreshToken: 'r', scope: 'mcp', tokenEndpoint: 'https://a.test/oauth/token' }, path);
+        saveCachedGrant('https://b.test', { clientId: 'c2', refreshToken: 'r2', scope: 'mcp', tokenEndpoint: 'https://b.test/oauth/token' }, path);
+        expect(loadCachedGrant('https://a.test', path)?.clientId).toBe('c');
+        expect(loadCachedGrant('https://b.test', path)?.refreshToken).toBe('r2');
+        expect(loadCachedGrant('https://missing.test', path)).toBeNull();
+        // 0600 perms (owner rw only)
+        const mode = statSync(path).mode & 0o777;
+        expect(mode).toBe(0o600);
+    });
+    it('clearCachedGrant removes only the target origin', () => {
+        saveCachedGrant('https://a.test', { clientId: 'c', refreshToken: 'r', scope: 'mcp', tokenEndpoint: 'e' }, path);
+        saveCachedGrant('https://b.test', { clientId: 'c2', refreshToken: 'r2', scope: 'mcp', tokenEndpoint: 'e' }, path);
+        clearCachedGrant('https://a.test', path);
+        expect(loadCachedGrant('https://a.test', path)).toBeNull();
+        expect(loadCachedGrant('https://b.test', path)).not.toBeNull();
+        const file = JSON.parse(readFileSync(path, 'utf8'));
+        expect(Object.keys(file)).toEqual(['https://b.test']);
+    });
+});
+describe('createTokenProvider', () => {
+    // expiresAt comfortably larger than EXPIRY_SKEW_MS so "fresh" and "within
+    // skew" are both expressible with a fake clock.
+    const base = { accessToken: 'at0', refreshToken: 'rt0', expiresAt: 10_000_000, scope: 'mcp' };
+    it('returns the cached access token while fresh', async () => {
+        const refresh = vi.fn();
+        const now = () => 0; // well before expiry
+        const p = createTokenProvider(base, refresh, undefined, now);
+        expect(await p.getAccessToken()).toBe('at0');
+        expect(refresh).not.toHaveBeenCalled();
+    });
+    it('refreshes when within the expiry skew and rotates the refresh token', async () => {
+        const refresh = vi.fn().mockResolvedValue({ accessToken: 'at1', refreshToken: 'rt1', expiresAt: 10_000_000, scope: 'mcp' });
+        const onRefreshed = vi.fn();
+        const now = () => base.expiresAt - EXPIRY_SKEW_MS + 1; // inside skew window
+        const p = createTokenProvider(base, refresh, onRefreshed, now);
+        expect(await p.getAccessToken()).toBe('at1');
+        expect(refresh).toHaveBeenCalledWith('rt0');
+        expect(onRefreshed).toHaveBeenCalledWith(expect.objectContaining({ refreshToken: 'rt1' }));
+    });
+    it('forceRefresh renews on demand (401 path)', async () => {
+        const refresh = vi.fn().mockResolvedValue({ accessToken: 'at2', refreshToken: 'rt2', expiresAt: 10_000_000, scope: 'mcp' });
+        const p = createTokenProvider(base, refresh, undefined, () => 0);
+        expect(await p.forceRefresh()).toBe('at2');
+        expect(refresh).toHaveBeenCalledOnce();
+    });
+    it('preserves the prior refresh token if the AS omits a new one', async () => {
+        const refresh = vi.fn().mockResolvedValue({ accessToken: 'at3', refreshToken: null, expiresAt: 10_000_000, scope: 'mcp' });
+        const onRefreshed = vi.fn();
+        const p = createTokenProvider(base, refresh, onRefreshed, () => base.expiresAt);
+        await p.getAccessToken();
+        expect(onRefreshed).toHaveBeenCalledWith(expect.objectContaining({ refreshToken: 'rt0' }));
+    });
+    it('throws a clear error when no refresh token is available', async () => {
+        const noRefresh = { ...base, refreshToken: null };
+        const p = createTokenProvider(noRefresh, vi.fn(), undefined, () => base.expiresAt);
+        await expect(p.getAccessToken()).rejects.toThrow(/reconnect the client/);
+    });
+    it('ORB-1419 - single-flights concurrent getAccessToken calls into ONE refresh', async () => {
+        // Two concurrent callers that both see an expired token must share a single
+        // in-flight refresh rather than each firing one (which would present the OLD
+        // refresh token twice and trip server-side reuse-detection).
+        let resolveRefresh = () => { };
+        const refresh = vi.fn().mockImplementation(() => new Promise((r) => { resolveRefresh = r; }));
+        const p = createTokenProvider(base, refresh, undefined, () => base.expiresAt);
+        const a = p.getAccessToken();
+        const b = p.getAccessToken();
+        // Both callers are now awaiting; only one refresh should have been started.
+        expect(refresh).toHaveBeenCalledOnce();
+        expect(refresh).toHaveBeenCalledWith('rt0');
+        resolveRefresh({ accessToken: 'at-shared', refreshToken: 'rt1', expiresAt: 10_000_000, scope: 'mcp' });
+        expect(await a).toBe('at-shared');
+        expect(await b).toBe('at-shared');
+        expect(refresh).toHaveBeenCalledOnce();
+    });
+});
+describe('bootstrapOAuth cached-grant path', () => {
+    let dir;
+    let path;
+    beforeEach(() => {
+        dir = mkdtempSync(join(tmpdir(), 'orboto-oauth-'));
+        path = join(dir, 'cache.json');
+    });
+    afterEach(() => rmSync(dir, { recursive: true, force: true }));
+    it('refreshes silently from a cached grant without opening a browser', async () => {
+        saveCachedGrant('https://x.test', {
+            clientId: 'cid', refreshToken: 'rt0', scope: 'mcp offline_access', tokenEndpoint: 'https://x.test/oauth/token',
+        }, path);
+        const fetchImpl = vi.fn().mockResolvedValue(jsonResponse({
+            access_token: 'fresh-at', refresh_token: 'rt1', expires_in: 3600, scope: 'mcp offline_access',
+        }));
+        const openBrowser = vi.fn();
+        const provider = await bootstrapOAuth({
+            apiBaseUrl: 'https://x.test/api', fetchImpl, openBrowser, cachePath: path, log: () => { },
+        });
+        expect(await provider.getAccessToken()).toBe('fresh-at');
+        expect(openBrowser).not.toHaveBeenCalled();
+        // rotation persisted
+        expect(loadCachedGrant('https://x.test', path)?.refreshToken).toBe('rt1');
+    });
+    it('clears a dead cached grant and falls through to discovery', async () => {
+        saveCachedGrant('https://x.test', {
+            clientId: 'cid', refreshToken: 'dead', scope: 'mcp', tokenEndpoint: 'https://x.test/oauth/token',
+        }, path);
+        // First call (refresh) 400s; then discovery is attempted (which we fail so
+        // we don't need to drive the whole interactive flow) - the point is the
+        // dead grant is cleared and discovery is reached.
+        const fetchImpl = vi.fn()
+            .mockResolvedValueOnce(new Response('{"error":"invalid_grant"}', { status: 400 })) // refresh
+            .mockResolvedValueOnce(new Response('nope', { status: 500 })); // discovery
+        await expect(bootstrapOAuth({
+            apiBaseUrl: 'https://x.test/api', fetchImpl: fetchImpl,
+            openBrowser: vi.fn(), cachePath: path, log: () => { },
+        })).rejects.toThrow(/discovery failed/);
+        expect(loadCachedGrant('https://x.test', path)).toBeNull();
+    });
+});

package/dist/orboto-client.js

@@ -0,0 +1,250 @@
+/**
+ * ORB-244 Phase A - thin HTTP client the MCP server uses to talk to
+ * the orboto API.
+ *
+ * Deliberately speaks HTTPS-REST rather than importing `@orboto/api`'s
+ * services directly, for three reasons:
+ *   1. One code path covers both delivery variants from the ticket -
+ *      Local-Proxy (`npx @orboto/mcp-cli`, running on the dev's laptop,
+ *      pointing at the public orboto URL) AND Self-Hosted-inline
+ *      (separate container in docker-compose, pointing at
+ *      `http://api:3000`). The only difference is the env var.
+ *   2. The API's `requirePermission` / PBAC cascade runs server-side
+ *      where it belongs. The MCP server is a pure transport adapter;
+ *      it never sees the DB or trust boundary.
+ *   3. The `orb_*` API-key flow is already wired into the API's
+ *      `authenticate` decorator - reusing it means the existing
+ *      `mcp:use` + `api:use` scope checks, rate limits, and audit
+ *      logs all light up for free.
+ *
+ * Every request adds `Authorization: Bearer <apiKey>` (from env) and
+ * a `User-Agent: orboto-mcp/<version>` header for the admin UI to
+ * distinguish MCP traffic from regular API traffic. Non-2xx responses
+ * throw `OrbotoApiError` so tool handlers can translate to MCP's
+ * `{isError: true}` shape.
+ */
+import { VERSION } from './version.js';
+export class OrbotoApiError extends Error {
+    status;
+    body;
+    url;
+    constructor(status, body, url) {
+        super(`orboto API ${status}: ${body || '(empty body)'}`);
+        this.status = status;
+        this.body = body;
+        this.url = url;
+        this.name = 'OrbotoApiError';
+    }
+}
+export class OrbotoClient {
+    baseUrl;
+    /** Headers common to every request EXCEPT Authorization, which is resolved
+     *  per-request so an OAuth token provider can rotate the bearer. */
+    baseHeaders;
+    apiKey;
+    tokenProvider;
+    constructor(config) {
+        this.baseUrl = config.baseUrl.replace(/\/+$/, '');
+        if (!config.apiKey && !config.tokenProvider) {
+            throw new Error('OrbotoClient requires either an apiKey or a tokenProvider');
+        }
+        this.apiKey = config.apiKey;
+        this.tokenProvider = config.tokenProvider;
+        // User-Agent shape: `orboto-mcp/<version> (claude-desktop)`. The
+        // suffix is optional metadata so the admin's MCP-usage panel
+        // (Phase F) can group calls per client family without needing a
+        // new DB column.
+        const ua = config.userAgentSuffix
+            ? `orboto-mcp/${VERSION} (${config.userAgentSuffix})`
+            : `orboto-mcp/${VERSION}`;
+        this.baseHeaders = {
+            'User-Agent': ua,
+            Accept: 'application/json',
+        };
+    }
+    async bearer(forceRefresh = false) {
+        if (this.tokenProvider) {
+            return forceRefresh ? this.tokenProvider.forceRefresh() : this.tokenProvider.getAccessToken();
+        }
+        return this.apiKey;
+    }
+    fullUrl(path) {
+        return `${this.baseUrl}${path.startsWith('/') ? '' : '/'}${path}`;
+    }
+    /**
+     * Auth-aware fetch. Injects the resolved bearer and, when an OAuth token
+     * provider is in play, retries a single 401 after a forced refresh - so an
+     * access token that expired (or was rotated by the api) is renewed inline
+     * instead of surfacing a spurious auth error to the tool caller. Throws
+     * `OrbotoApiError` on a non-2xx (after the retry). Returns the raw Response
+     * so callers parse json/text/binary as they need.
+     */
+    /** ORB-1727 - unread-inbox count from the latest api response header. */
+    pendingAgentMail = 0;
+    async authedFetch(url, init, accept) {
+        const doFetch = async (token) => {
+            const headers = {
+                ...this.baseHeaders,
+                ...(accept ? { Accept: accept } : {}),
+                ...(init.headers ?? {}),
+                Authorization: `Bearer ${token}`,
+            };
+            return fetch(url, { ...init, headers });
+        };
+        let res = await doFetch(await this.bearer());
+        if (res.status === 401 && this.tokenProvider) {
+            res = await doFetch(await this.bearer(true));
+        }
+        // ORB-1727 - the api stamps `x-orboto-agent-mail: <count>` on responses
+        // while the caller has unread inbox messages. Capture it centrally so
+        // the tool-response wrapper can nudge without any extra request.
+        const mail = res.headers?.get?.('x-orboto-agent-mail');
+        this.pendingAgentMail = mail ? Number(mail) || 0 : 0;
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            throw new OrbotoApiError(res.status, body, url);
+        }
+        return res;
+    }
+    /** GET a JSON endpoint. Throws `OrbotoApiError` on non-2xx. */
+    async get(path) {
+        const res = await this.authedFetch(this.fullUrl(path), { method: 'GET' });
+        return (await res.json());
+    }
+    /** POST a JSON body. */
+    async post(path, body) {
+        const res = await this.authedFetch(this.fullUrl(path), {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+        if (res.status === 204)
+            return undefined;
+        return (await res.json());
+    }
+    /** PATCH a JSON body. */
+    async patch(path, body) {
+        const res = await this.authedFetch(this.fullUrl(path), {
+            method: 'PATCH',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+        return (await res.json());
+    }
+    async put(path, body) {
+        const res = await this.authedFetch(this.fullUrl(path), {
+            method: 'PUT',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+        return (await res.json());
+    }
+    /** DELETE. Returns the parsed body when the route sends one (some
+     *  DELETEs 204, others return the mutated row - ORB-626 cancel does).
+     *
+     *  ORB-1610 - `body` is optional and, when present (including `{}`),
+     *  is sent as a real JSON body with `Content-Type: application/json`.
+     *  A genuinely bodyless DELETE against a route whose schema declares
+     *  `body: SomeSchema.optional()` 400s on Fastify's content-type
+     *  parser (verified against `DELETE /work-sessions/:id/claims`) - a
+     *  caller that means "release everything" must send `{}`, not omit
+     *  the body entirely. */
+    async delete(path, body) {
+        const res = await this.authedFetch(this.fullUrl(path), {
+            method: 'DELETE',
+            ...(body !== undefined ? { headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) } : {}),
+        });
+        if (res.status === 204)
+            return undefined;
+        const text = await res.text();
+        return (text ? JSON.parse(text) : undefined);
+    }
+    /**
+     * POST a `multipart/form-data` payload - used by ingest-file +
+     * attachment upload tools (ORB-799). The fetch API picks the boundary
+     * automatically when we let it set `Content-Type`, so we deliberately
+     * do NOT set `Content-Type: application/json` from the JSON helpers.
+     */
+    async postMultipart(path, form) {
+        const res = await this.authedFetch(this.fullUrl(path), {
+            method: 'POST',
+            body: form, // no Content-Type - fetch sets the boundary
+        });
+        if (res.status === 204)
+            return undefined;
+        return (await res.json());
+    }
+    /**
+     * GET an endpoint that returns plain text (Markdown export, CSV
+     * downloads, etc.) - bypasses the `Accept: application/json` header
+     * + the JSON-only parsing in `get()`. Returns the raw response body
+     * as a string. (ORB-915.)
+     */
+    async getText(path) {
+        const res = await this.authedFetch(this.fullUrl(path), { method: 'GET' }, '*/*');
+        return await res.text();
+    }
+    /**
+     * POST an endpoint that returns a binary body (PDF export, ZIP
+     * download, etc.). Returns the raw bytes as a Uint8Array - caller
+     * decides whether to base64 it for an MCP resource attachment or
+     * spill it to disk. (ORB-915.)
+     */
+    async postBinary(path, body) {
+        const res = await this.authedFetch(this.fullUrl(path), {
+            method: 'POST',
+            headers: body !== undefined ? { 'Content-Type': 'application/json' } : undefined,
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        }, '*/*');
+        const ab = await res.arrayBuffer();
+        return {
+            bytes: new Uint8Array(ab),
+            contentType: res.headers.get('content-type') ?? 'application/octet-stream',
+        };
+    }
+    /**
+     * GET an endpoint that returns a binary body (backup-run ZIP download,
+     * etc.). Same shape as postBinary, GET method. (ORB-1301.)
+     */
+    async getBinary(path) {
+        const res = await this.authedFetch(this.fullUrl(path), { method: 'GET' }, '*/*');
+        const ab = await res.arrayBuffer();
+        return {
+            bytes: new Uint8Array(ab),
+            contentType: res.headers.get('content-type') ?? 'application/octet-stream',
+        };
+    }
+}
+/**
+ * Preflight a new MCP session: verify the workspace has MCP enabled,
+ * the user holds the `mcp:use` permission, AND the user has not flipped
+ * their own MCP opt-out (ORB-942). Called once per session (stdio boot /
+ * HTTP initialize) and again on every rehydrate/adopt, so all three
+ * gates share one enforcement point. Throws a descriptive `Error` on any
+ * failure so the caller can translate to an MCP refuse-to-initialize
+ * response.
+ */
+export async function preflightMcpSession(client) {
+    let status;
+    try {
+        status = await client.get('/system/mcp/status');
+    }
+    catch (err) {
+        if (err instanceof OrbotoApiError && err.status === 401) {
+            throw new Error('MCP preflight failed: the provided API key is invalid or expired.');
+        }
+        throw err;
+    }
+    if (!status.enabled) {
+        throw new Error('MCP preflight failed: the workspace administrator has disabled MCP access.');
+    }
+    if (!status.mcpUseGranted) {
+        throw new Error(`MCP preflight failed: user ${status.userEmail} lacks the mcp:use permission. Ask an admin to grant it.`);
+    }
+    // ORB-942 - per-user opt-out. Distinct message pointing at the toggle so
+    // the user knows this is their own setting, not an admin / permission block.
+    if (!status.userMcpEnabled) {
+        throw new Error('MCP preflight failed: you have disabled MCP access for your account. Re-enable it in Profile - Connect an AI Client.');
+    }
+    return { userEmail: status.userEmail };
+}

package/dist/orboto-client.test.js

@@ -0,0 +1,141 @@
+/**
+ * ORB-244 Phase A - orboto REST client unit tests.
+ *
+ * We mock `fetch` and cover the shape we promise to every tool
+ * handler: correct base URL, bearer header, User-Agent string,
+ * JSON body for write verbs, and the `OrbotoApiError` throw on
+ * non-2xx with status + body captured.
+ *
+ * `preflightMcpSession` is tested too because its three-way
+ * failure branching (401 / disabled / permission-denied) is the
+ * most likely regression surface when the API contract drifts.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient, OrbotoApiError, preflightMcpSession } from './orboto-client.js';
+beforeEach(() => { vi.restoreAllMocks(); });
+afterEach(() => { vi.restoreAllMocks(); });
+function mockFetch(response) {
+    const fullResponse = {
+        ok: response.ok ?? true,
+        status: response.status ?? 200,
+        statusText: response.statusText ?? 'OK',
+        json: response.json ?? (async () => ({})),
+        text: response.text ?? (async () => ''),
+    };
+    return vi.spyOn(globalThis, 'fetch').mockResolvedValue(fullResponse);
+}
+describe('OrbotoClient', () => {
+    it('strips trailing slashes from baseUrl', async () => {
+        const spy = mockFetch({ json: async () => ({ ok: true }) });
+        const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com///', apiKey: 'orb_test' });
+        await client.get('/projects');
+        expect(spy).toHaveBeenCalledWith('https://orboto.example.com/projects', expect.any(Object));
+    });
+    it('prepends a missing leading slash on path', async () => {
+        const spy = mockFetch({ json: async () => ({}) });
+        const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_test' });
+        await client.get('projects');
+        expect(spy).toHaveBeenCalledWith('https://orboto.example.com/projects', expect.any(Object));
+    });
+    it('sends Authorization: Bearer and User-Agent with optional client suffix', async () => {
+        const spy = mockFetch({ json: async () => ({}) });
+        const client = new OrbotoClient({
+            baseUrl: 'https://orboto.example.com',
+            apiKey: 'orb_test',
+            userAgentSuffix: 'claude-desktop',
+        });
+        await client.get('/projects');
+        const [, init] = spy.mock.calls[0];
+        const headers = init.headers;
+        expect(headers.Authorization).toBe('Bearer orb_test');
+        expect(headers['User-Agent']).toMatch(/^orboto-mcp\/[\d.]+ \(claude-desktop\)$/);
+    });
+    it('omits the UA suffix when userAgentSuffix is not set', async () => {
+        const spy = mockFetch({ json: async () => ({}) });
+        const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_test' });
+        await client.get('/projects');
+        const [, init] = spy.mock.calls[0];
+        const headers = init.headers;
+        expect(headers['User-Agent']).toMatch(/^orboto-mcp\/[\d.]+$/);
+    });
+    it('serialises POST body as JSON with Content-Type', async () => {
+        const spy = mockFetch({ json: async () => ({ created: true }) });
+        const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_test' });
+        await client.post('/tickets', { title: 'x' });
+        const [, init] = spy.mock.calls[0];
+        expect(init.method).toBe('POST');
+        expect(init.body).toBe('{"title":"x"}');
+        expect(init.headers['Content-Type']).toBe('application/json');
+    });
+    it('throws OrbotoApiError with captured status + body on non-2xx', async () => {
+        mockFetch({ ok: false, status: 403, text: async () => '{"error":"forbidden"}' });
+        const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_test' });
+        await expect(client.get('/forbidden')).rejects.toMatchObject({
+            name: 'OrbotoApiError',
+            status: 403,
+            body: '{"error":"forbidden"}',
+            url: 'https://orboto.example.com/forbidden',
+        });
+    });
+    it('returns undefined (not null) for 204', async () => {
+        mockFetch({ status: 204 });
+        const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_test' });
+        const result = await client.post('/action', {});
+        expect(result).toBeUndefined();
+    });
+    // ORB-799 - postMultipart sends FormData with no Content-Type header
+    // (fetch chooses the boundary). The bearer + UA headers still apply.
+    it('postMultipart sends FormData body without Content-Type (boundary picked by fetch)', async () => {
+        const spy = mockFetch({ json: async () => ({ docId: 'd1' }) });
+        const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_test' });
+        const form = new FormData();
+        form.append('file', new Blob([new Uint8Array([0x4d, 0x44])], { type: 'text/markdown' }), 'note.md');
+        const result = await client.postMultipart('/spaces/abc/docs/ingest-file', form);
+        expect(result).toEqual({ docId: 'd1' });
+        const [, init] = spy.mock.calls[0];
+        const headers = init.headers;
+        expect(headers.Authorization).toBe('Bearer orb_test');
+        // No Content-Type header - fetch sets multipart/form-data; boundary=…
+        expect(headers['Content-Type']).toBeUndefined();
+        expect(init.method).toBe('POST');
+    });
+    it('postMultipart throws OrbotoApiError on non-2xx', async () => {
+        mockFetch({ ok: false, status: 413, text: async () => 'payload too large' });
+        const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_test' });
+        const form = new FormData();
+        form.append('file', new Blob([new Uint8Array([0])], { type: 'application/octet-stream' }), 'x');
+        await expect(client.postMultipart('/x', form)).rejects.toBeInstanceOf(OrbotoApiError);
+    });
+});
+describe('preflightMcpSession', () => {
+    it('resolves {userEmail} when enabled + mcpUseGranted + userMcpEnabled', async () => {
+        mockFetch({ json: async () => ({ enabled: true, mcpUseGranted: true, userMcpEnabled: true, userEmail: 'a@b.c' }) });
+        const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_test' });
+        await expect(preflightMcpSession(client)).resolves.toEqual({ userEmail: 'a@b.c' });
+    });
+    it('throws the per-user opt-out message when userMcpEnabled=false (ORB-942)', async () => {
+        mockFetch({ json: async () => ({ enabled: true, mcpUseGranted: true, userMcpEnabled: false, userEmail: 'a@b.c' }) });
+        const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_test' });
+        await expect(preflightMcpSession(client)).rejects.toThrow(/you have disabled MCP access for your account/);
+    });
+    it('throws a helpful message when the API returns 401 (bad token)', async () => {
+        mockFetch({ ok: false, status: 401, text: async () => 'Invalid API key' });
+        const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_bad' });
+        await expect(preflightMcpSession(client)).rejects.toThrow(/API key is invalid or expired/);
+    });
+    it('throws when the workspace has mcp_enabled=false', async () => {
+        mockFetch({ json: async () => ({ enabled: false, mcpUseGranted: true, userEmail: 'a@b.c' }) });
+        const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_test' });
+        await expect(preflightMcpSession(client)).rejects.toThrow(/administrator has disabled MCP/);
+    });
+    it('throws when the user lacks mcp:use', async () => {
+        mockFetch({ json: async () => ({ enabled: true, mcpUseGranted: false, userEmail: 'a@b.c' }) });
+        const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_test' });
+        await expect(preflightMcpSession(client)).rejects.toThrow(/lacks the mcp:use permission/);
+    });
+    it('propagates non-401 errors verbatim', async () => {
+        mockFetch({ ok: false, status: 503, text: async () => 'Service unavailable' });
+        const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_test' });
+        await expect(preflightMcpSession(client)).rejects.toBeInstanceOf(OrbotoApiError);
+    });
+});