sophos-central-mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,160 @@
+# Sophos Central MCP Server
+
+MCP (Model Context Protocol) server for interacting with Sophos Central APIs. Supports partner, organisation, and single-tenant credential types with automatic region routing.
+
+## Quick Start
+
+No installation needed. Add the following to your `claude_desktop_config.json` (Claude Desktop) or equivalent MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "sophos-central": {
+      "command": "npx",
+      "args": ["-y", "sophos-central-mcp-server"],
+      "env": {
+        "SOPHOS_CLIENT_ID": "your-client-id",
+        "SOPHOS_CLIENT_SECRET": "your-client-secret",
+        "TRANSPORT": "stdio"
+      }
+    }
+  }
+}
+```
+
+Replace `your-client-id` and `your-client-secret` with your [Sophos Central API credentials](#creating-api-credentials). Claude Desktop will download and run the server automatically on first use.
+
+### Claude Code
+
+```bash
+SOPHOS_CLIENT_ID=xxx SOPHOS_CLIENT_SECRET=yyy TRANSPORT=stdio \
+  claude mcp add sophos-central -- npx -y sophos-central-mcp-server
+```
+
+## Features
+
+- **Universal caller support**: Works with partner, organisation, and tenant-level API credentials
+- **Multi-tenant**: Partner/org callers can query across all managed tenants
+- **Auto region routing**: Discovers tenant data regions via `/whoami/v1` and routes requests to the correct regional API host
+- **Token lifecycle**: Automatic OAuth2 token refresh before expiry
+- **Rate limit handling**: Retry with backoff on 429 responses
+- **Dual transport**: Streamable HTTP (for Claude Desktop / Claude Code) or stdio
+
+## Prerequisites
+
+- Node.js 20 or later
+- Sophos Central API credentials (Client ID + Client Secret)
+
+### Creating API Credentials
+
+**Tenant-level**: In Sophos Central, go to **Settings > API Credentials Management** and create a new credential.
+
+**Partner-level**: In the Sophos Partner Dashboard, create API credentials under **Settings > API Credentials**.
+
+**Organisation-level**: In Sophos Central Enterprise, use **Global Settings > API Credentials Management**.
+
+## Configuration
+
+Copy `.env.example` to `.env` and set your credentials:
+
+```
+SOPHOS_CLIENT_ID=your-client-id
+SOPHOS_CLIENT_SECRET=your-client-secret
+PORT=3100
+TRANSPORT=http
+```
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `SOPHOS_CLIENT_ID` | Yes | - | OAuth2 client ID |
+| `SOPHOS_CLIENT_SECRET` | Yes | - | OAuth2 client secret |
+| `SOPHOS_TENANT_ID` | No | - | Lock to a single tenant (useful for tenant-level creds) |
+| `PORT` | No | 3100 | HTTP server port |
+| `TRANSPORT` | No | http | `http` for streamable HTTP, `stdio` for subprocess mode |
+
+## Tools
+
+### SOC Monitoring
+
+| Tool | Description |
+|------|-------------|
+| `sophos_list_tenants` | List managed tenants (partner/org only) |
+| `sophos_list_alerts` | List alerts with severity/category/product/date filters |
+| `sophos_get_alert` | Get full alert detail with allowed actions |
+| `sophos_acknowledge_alert` | Mark an alert as reviewed |
+| `sophos_list_endpoints` | List endpoints with health/OS/hostname/isolation filters |
+| `sophos_get_endpoint` | Get full endpoint detail |
+| `sophos_scan_endpoint` | Trigger an on-demand scan |
+| `sophos_isolate_endpoint` | Network-isolate a compromised endpoint |
+| `sophos_release_endpoint` | Release an endpoint from isolation |
+| `sophos_get_account_health` | Get tenant health check scores |
+| `sophos_list_users` | List directory users |
+| `sophos_list_admins` | List admin accounts and roles |
+
+### Tenant context
+
+For **partner/org** callers, every tenant-scoped tool requires a `tenant_id` parameter. Use `sophos_list_tenants` first to discover available tenant IDs.
+
+For **tenant-level** callers, `tenant_id` is optional and defaults to the authenticated tenant.
+
+## Architecture
+
+```
+Authenticate (OAuth2 client credentials)
+    |
+    v
+/whoami/v1 -> Discover identity type (partner | organization | tenant)
+    |
+    v
+If partner/org: enumerate tenants, cache {tenantId -> apiHost}
+    |
+    v
+Register tools based on identity type
+    |
+    v
+Per tool call: resolve tenant -> regional API host -> execute request
+```
+
+### Key decisions
+
+- **Dynamic tool registration**: Only tools valid for the caller type are exposed to the LLM
+- **Explicit tenant context**: Partner/org callers must specify `tenant_id` to prevent cross-tenant accidents
+- **Stateless HTTP**: Each MCP request creates a fresh transport instance (no session affinity)
+- **Localhost binding**: HTTP server binds to `127.0.0.1` only
+
+## Project Structure
+
+```
+src/
+├── index.ts                  # Entry point, server bootstrap
+├── config/config.ts          # Environment config
+├── auth/token-manager.ts     # OAuth2 token lifecycle
+├── client/
+│   ├── sophos-client.ts      # HTTP client with region routing
+│   └── tenant-resolver.ts    # Whoami + tenant cache
+├── tools/
+│   ├── helpers.ts            # Shared response formatting
+│   ├── tenants.ts            # sophos_list_tenants
+│   ├── alerts.ts             # sophos_list_alerts, get, acknowledge
+│   ├── endpoints.ts          # sophos_list/get/scan/isolate/release
+│   ├── health.ts             # sophos_get_account_health
+│   └── directory.ts          # sophos_list_users, list_admins
+└── types/sophos.ts           # Sophos API response types
+```
+
+## Roadmap
+
+- **Phase 2 (Admin automation)**: Policies, endpoint groups, global exclusions, admin role management
+- **Phase 3 (Investigation)**: XDR Data Lake queries, Live Discover, detections, cases, SIEM events
+
+## Security
+
+- Credentials are read from environment variables only, never logged
+- JWT tokens are held in memory with automatic refresh
+- HTTP server binds to `127.0.0.1` (localhost only)
+- Write actions have `destructiveHint` annotations so clients can warn users
+- Partner/org callers require explicit `tenant_id` on every call
+
+## License
+
+MIT

package/dist/auth/token-manager.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Manages OAuth2 client credentials authentication with Sophos Central.
+ * Handles token acquisition and transparent refresh before expiry.
+ */
+export declare class TokenManager {
+    private clientId;
+    private clientSecret;
+    private accessToken;
+    private expiresAt;
+    private refreshPromise;
+    constructor(clientId: string, clientSecret: string);
+    /**
+     * Returns a valid access token, refreshing if needed.
+     * Deduplicates concurrent refresh requests.
+     */
+    getToken(): Promise<string>;
+    private fetchToken;
+}
+//# sourceMappingURL=token-manager.d.ts.map

package/dist/auth/token-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-manager.d.ts","sourceRoot":"","sources":["../../src/auth/token-manager.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,qBAAa,YAAY;IAMrB,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,YAAY;IANtB,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,SAAS,CAAa;IAC9B,OAAO,CAAC,cAAc,CAAgC;gBAG5C,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM;IAG9B;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC;YAoBnB,UAAU;CAqCzB"}

package/dist/auth/token-manager.js

@@ -0,0 +1,64 @@
+/**
+ * Manages OAuth2 client credentials authentication with Sophos Central.
+ * Handles token acquisition and transparent refresh before expiry.
+ */
+import { SOPHOS_AUTH_URL } from "../config/config.js";
+export class TokenManager {
+    clientId;
+    clientSecret;
+    accessToken = null;
+    expiresAt = 0;
+    refreshPromise = null;
+    constructor(clientId, clientSecret) {
+        this.clientId = clientId;
+        this.clientSecret = clientSecret;
+    }
+    /**
+     * Returns a valid access token, refreshing if needed.
+     * Deduplicates concurrent refresh requests.
+     */
+    async getToken() {
+        // If token is valid for at least 60 more seconds, return it
+        if (this.accessToken && Date.now() < this.expiresAt - 60_000) {
+            return this.accessToken;
+        }
+        // Deduplicate concurrent refresh calls
+        if (this.refreshPromise) {
+            return this.refreshPromise;
+        }
+        this.refreshPromise = this.fetchToken();
+        try {
+            const token = await this.refreshPromise;
+            return token;
+        }
+        finally {
+            this.refreshPromise = null;
+        }
+    }
+    async fetchToken() {
+        const body = new URLSearchParams({
+            grant_type: "client_credentials",
+            client_id: this.clientId,
+            client_secret: this.clientSecret,
+            scope: "token",
+        });
+        const response = await fetch(SOPHOS_AUTH_URL, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: body.toString(),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Sophos auth failed (${response.status}): ${errorText}`);
+        }
+        const data = (await response.json());
+        if (data.errorCode) {
+            throw new Error(`Sophos auth error: ${data.errorCode} - ${data.message}`);
+        }
+        this.accessToken = data.access_token;
+        this.expiresAt = Date.now() + data.expires_in * 1000;
+        console.error(`[sophos-auth] Token acquired, expires in ${data.expires_in}s`);
+        return this.accessToken;
+    }
+}
+//# sourceMappingURL=token-manager.js.map

package/dist/auth/token-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-manager.js","sourceRoot":"","sources":["../../src/auth/token-manager.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAGtD,MAAM,OAAO,YAAY;IAMb;IACA;IANF,WAAW,GAAkB,IAAI,CAAC;IAClC,SAAS,GAAW,CAAC,CAAC;IACtB,cAAc,GAA2B,IAAI,CAAC;IAEtD,YACU,QAAgB,EAChB,YAAoB;QADpB,aAAQ,GAAR,QAAQ,CAAQ;QAChB,iBAAY,GAAZ,YAAY,CAAQ;IAC3B,CAAC;IAEJ;;;OAGG;IACH,KAAK,CAAC,QAAQ;QACZ,4DAA4D;QAC5D,IAAI,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,SAAS,GAAG,MAAM,EAAE,CAAC;YAC7D,OAAO,IAAI,CAAC,WAAW,CAAC;QAC1B,CAAC;QAED,uCAAuC;QACvC,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACxB,OAAO,IAAI,CAAC,cAAc,CAAC;QAC7B,CAAC;QAED,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;QACxC,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC;YACxC,OAAO,KAAK,CAAC;QACf,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAC7B,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,UAAU;QACtB,MAAM,IAAI,GAAG,IAAI,eAAe,CAAC;YAC/B,UAAU,EAAE,oBAAoB;YAChC,SAAS,EAAE,IAAI,CAAC,QAAQ;YACxB,aAAa,EAAE,IAAI,CAAC,YAAY;YAChC,KAAK,EAAE,OAAO;SACf,CAAC,CAAC;QAEH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,eAAe,EAAE;YAC5C,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,mCAAmC,EAAE;YAChE,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE;SACtB,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;YACxC,MAAM,IAAI,KAAK,CACb,uBAAuB,QAAQ,CAAC,MAAM,MAAM,SAAS,EAAE,CACxD,CAAC;QACJ,CAAC;QAED,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAwB,CAAC;QAE5D,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CACb,sBAAsB,IAAI,CAAC,SAAS,MAAM,IAAI,CAAC,OAAO,EAAE,CACzD,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,YAAY,CAAC;QACrC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QAErD,OAAO,CAAC,KAAK,CACX,4CAA4C,IAAI,CAAC,UAAU,GAAG,CAC/D,CAAC;QACF,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;CACF"}

package/dist/client/sophos-client.d.ts

@@ -0,0 +1,33 @@
+/**
+ * HTTP client for Sophos Central APIs.
+ * Handles region-aware routing, auth headers, retries, and error mapping.
+ */
+import type { TokenManager } from "../auth/token-manager.js";
+import type { TenantResolver } from "./tenant-resolver.js";
+export interface RequestOptions {
+    /** HTTP method */
+    method?: "GET" | "POST" | "PATCH" | "DELETE";
+    /** Query parameters */
+    params?: Record<string, string>;
+    /** JSON request body */
+    body?: unknown;
+    /** Additional headers */
+    headers?: Record<string, string>;
+}
+export declare class SophosClient {
+    private tokenManager;
+    private tenantResolver;
+    constructor(tokenManager: TokenManager, tenantResolver: TenantResolver);
+    /**
+     * Make a request to a tenant-scoped API endpoint.
+     * Automatically resolves the regional API host for the tenant.
+     */
+    tenantRequest<T>(tenantId: string, path: string, options?: RequestOptions): Promise<T>;
+    /**
+     * Make a request to a global API endpoint (partner/org level).
+     */
+    globalRequest<T>(path: string, options?: RequestOptions): Promise<T>;
+    private executeWithRetry;
+    private sleep;
+}
+//# sourceMappingURL=sophos-client.d.ts.map

package/dist/client/sophos-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sophos-client.d.ts","sourceRoot":"","sources":["../../src/client/sophos-client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAG3D,MAAM,WAAW,cAAc;IAC7B,kBAAkB;IAClB,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;IAC7C,uBAAuB;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,wBAAwB;IACxB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,yBAAyB;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,qBAAa,YAAY;IAErB,OAAO,CAAC,YAAY;IACpB,OAAO,CAAC,cAAc;gBADd,YAAY,EAAE,YAAY,EAC1B,cAAc,EAAE,cAAc;IAGxC;;;OAGG;IACG,aAAa,CAAC,CAAC,EACnB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,CAAC,CAAC;IAgCb;;OAEG;IACG,aAAa,CAAC,CAAC,EACnB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,CAAC,CAAC;YAiCC,gBAAgB;IAqE9B,OAAO,CAAC,KAAK;CAGd"}

package/dist/client/sophos-client.js

@@ -0,0 +1,126 @@
+/**
+ * HTTP client for Sophos Central APIs.
+ * Handles region-aware routing, auth headers, retries, and error mapping.
+ */
+export class SophosClient {
+    tokenManager;
+    tenantResolver;
+    constructor(tokenManager, tenantResolver) {
+        this.tokenManager = tokenManager;
+        this.tenantResolver = tenantResolver;
+    }
+    /**
+     * Make a request to a tenant-scoped API endpoint.
+     * Automatically resolves the regional API host for the tenant.
+     */
+    async tenantRequest(tenantId, path, options = {}) {
+        const apiHost = await this.tenantResolver.resolveApiHost(tenantId);
+        const token = await this.tokenManager.getToken();
+        const url = new URL(`${apiHost}${path}`);
+        if (options.params) {
+            for (const [key, value] of Object.entries(options.params)) {
+                if (value !== undefined && value !== "") {
+                    url.searchParams.set(key, value);
+                }
+            }
+        }
+        const headers = {
+            Authorization: `Bearer ${token}`,
+            "X-Tenant-ID": tenantId,
+            "Content-Type": "application/json",
+            ...options.headers,
+        };
+        const fetchOptions = {
+            method: options.method || "GET",
+            headers,
+        };
+        if (options.body) {
+            fetchOptions.body = JSON.stringify(options.body);
+        }
+        return this.executeWithRetry(url.toString(), fetchOptions);
+    }
+    /**
+     * Make a request to a global API endpoint (partner/org level).
+     */
+    async globalRequest(path, options = {}) {
+        const identity = this.tenantResolver.getIdentity();
+        const token = await this.tokenManager.getToken();
+        const idHeader = this.tenantResolver.getIdHeader();
+        const url = new URL(`${identity.apiHosts.global}${path}`);
+        if (options.params) {
+            for (const [key, value] of Object.entries(options.params)) {
+                if (value !== undefined && value !== "") {
+                    url.searchParams.set(key, value);
+                }
+            }
+        }
+        const headers = {
+            Authorization: `Bearer ${token}`,
+            [idHeader.name]: idHeader.value,
+            "Content-Type": "application/json",
+            ...options.headers,
+        };
+        const fetchOptions = {
+            method: options.method || "GET",
+            headers,
+        };
+        if (options.body) {
+            fetchOptions.body = JSON.stringify(options.body);
+        }
+        return this.executeWithRetry(url.toString(), fetchOptions);
+    }
+    async executeWithRetry(url, options, retries = 2) {
+        let lastError = null;
+        for (let attempt = 0; attempt <= retries; attempt++) {
+            try {
+                const response = await fetch(url, options);
+                if (response.status === 429) {
+                    // Rate limited: wait and retry
+                    const retryAfter = response.headers.get("Retry-After");
+                    const waitMs = retryAfter ? parseInt(retryAfter, 10) * 1000 : 5000;
+                    console.error(`[sophos-client] Rate limited, waiting ${waitMs}ms (attempt ${attempt + 1})`);
+                    await this.sleep(waitMs);
+                    continue;
+                }
+                if (!response.ok) {
+                    const errorBody = await response.text();
+                    let parsed = null;
+                    try {
+                        parsed = JSON.parse(errorBody);
+                    }
+                    catch {
+                        // Not JSON
+                    }
+                    const msg = parsed
+                        ? `Sophos API error: ${parsed.error} - ${parsed.message}${parsed.correlationId ? ` (correlationId: ${parsed.correlationId})` : ""}`
+                        : `Sophos API error (${response.status}): ${errorBody.slice(0, 500)}`;
+                    throw new Error(msg);
+                }
+                // Some endpoints return 204 No Content
+                if (response.status === 204) {
+                    return {};
+                }
+                return (await response.json());
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+                // Don't retry on auth or client errors
+                if (lastError.message.includes("401") ||
+                    lastError.message.includes("403") ||
+                    lastError.message.includes("404")) {
+                    throw lastError;
+                }
+                if (attempt < retries) {
+                    const backoff = Math.pow(2, attempt) * 1000;
+                    console.error(`[sophos-client] Request failed, retrying in ${backoff}ms: ${lastError.message}`);
+                    await this.sleep(backoff);
+                }
+            }
+        }
+        throw lastError || new Error("Request failed after retries");
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+//# sourceMappingURL=sophos-client.js.map

package/dist/client/sophos-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sophos-client.js","sourceRoot":"","sources":["../../src/client/sophos-client.ts"],"names":[],"mappings":"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"}

package/dist/client/tenant-resolver.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Discovers the caller's identity type via /whoami/v1 and resolves
+ * tenant IDs to their regional API hosts. Caches the mapping.
+ */
+import type { TokenManager } from "../auth/token-manager.js";
+import type { SophosIdType } from "../types/sophos.js";
+export interface TenantInfo {
+    id: string;
+    name: string;
+    apiHost: string;
+    dataRegion: string;
+    dataGeography: string;
+}
+export interface CallerIdentity {
+    id: string;
+    idType: SophosIdType;
+    apiHosts: {
+        global: string;
+        dataRegion?: string;
+    };
+}
+export declare class TenantResolver {
+    private tokenManager;
+    private identity;
+    private tenantCache;
+    private tenantsLoaded;
+    constructor(tokenManager: TokenManager);
+    /**
+     * Initialise: calls /whoami/v1 and discovers the caller identity.
+     */
+    init(): Promise<CallerIdentity>;
+    getIdentity(): CallerIdentity;
+    /**
+     * Returns the ID type header name needed for partner/org API calls.
+     */
+    getIdHeader(): {
+        name: string;
+        value: string;
+    };
+    /**
+     * Loads all tenants for partner/org callers. Paginates through all pages.
+     */
+    loadTenants(): Promise<TenantInfo[]>;
+    /**
+     * Resolves a tenant ID to its API host. Loads tenants if not cached.
+     */
+    resolveApiHost(tenantId: string): Promise<string>;
+    /**
+     * Returns the tenant ID to use. For single-tenant callers, returns the
+     * identity ID. For partner/org callers, requires an explicit tenant ID.
+     */
+    resolveTenantId(providedTenantId?: string): string;
+    /**
+     * Returns all cached tenants.
+     */
+    getCachedTenants(): TenantInfo[];
+}
+//# sourceMappingURL=tenant-resolver.d.ts.map

package/dist/client/tenant-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-resolver.d.ts","sourceRoot":"","sources":["../../src/client/tenant-resolver.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,KAAK,EACV,YAAY,EAIb,MAAM,oBAAoB,CAAC;AAE5B,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,YAAY,CAAC;IACrB,QAAQ,EAAE;QACR,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED,qBAAa,cAAc;IAKb,OAAO,CAAC,YAAY;IAJhC,OAAO,CAAC,QAAQ,CAA+B;IAC/C,OAAO,CAAC,WAAW,CAAiC;IACpD,OAAO,CAAC,aAAa,CAAS;gBAEV,YAAY,EAAE,YAAY;IAE9C;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,cAAc,CAAC;IAqCrC,WAAW,IAAI,cAAc;IAO7B;;OAEG;IACH,WAAW,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE;IAY9C;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAoE1C;;OAEG;IACG,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAmBvD;;;OAGG;IACH,eAAe,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,MAAM;IAiBlD;;OAEG;IACH,gBAAgB,IAAI,UAAU,EAAE;CAGjC"}

package/dist/client/tenant-resolver.js

@@ -0,0 +1,158 @@
+/**
+ * Discovers the caller's identity type via /whoami/v1 and resolves
+ * tenant IDs to their regional API hosts. Caches the mapping.
+ */
+import { SOPHOS_GLOBAL_API } from "../config/config.js";
+export class TenantResolver {
+    tokenManager;
+    identity = null;
+    tenantCache = new Map();
+    tenantsLoaded = false;
+    constructor(tokenManager) {
+        this.tokenManager = tokenManager;
+    }
+    /**
+     * Initialise: calls /whoami/v1 and discovers the caller identity.
+     */
+    async init() {
+        const token = await this.tokenManager.getToken();
+        const response = await fetch(`${SOPHOS_GLOBAL_API}/whoami/v1`, {
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Whoami failed (${response.status}): ${errorText}`);
+        }
+        const data = (await response.json());
+        this.identity = {
+            id: data.id,
+            idType: data.idType,
+            apiHosts: data.apiHosts,
+        };
+        console.error(`[sophos-tenant] Identity: ${data.idType} (${data.id})`);
+        // For tenant-level callers, the data region host is returned directly
+        if (data.idType === "tenant" && data.apiHosts.dataRegion) {
+            this.tenantCache.set(data.id, {
+                id: data.id,
+                name: "self",
+                apiHost: data.apiHosts.dataRegion,
+                dataRegion: "self",
+                dataGeography: "unknown",
+            });
+            this.tenantsLoaded = true;
+        }
+        return this.identity;
+    }
+    getIdentity() {
+        if (!this.identity) {
+            throw new Error("TenantResolver not initialised. Call init() first.");
+        }
+        return this.identity;
+    }
+    /**
+     * Returns the ID type header name needed for partner/org API calls.
+     */
+    getIdHeader() {
+        const identity = this.getIdentity();
+        switch (identity.idType) {
+            case "partner":
+                return { name: "X-Partner-ID", value: identity.id };
+            case "organization":
+                return { name: "X-Organization-ID", value: identity.id };
+            case "tenant":
+                return { name: "X-Tenant-ID", value: identity.id };
+        }
+    }
+    /**
+     * Loads all tenants for partner/org callers. Paginates through all pages.
+     */
+    async loadTenants() {
+        const identity = this.getIdentity();
+        if (identity.idType === "tenant") {
+            return Array.from(this.tenantCache.values());
+        }
+        if (this.tenantsLoaded) {
+            return Array.from(this.tenantCache.values());
+        }
+        const apiPath = identity.idType === "partner"
+            ? "/partner/v1/tenants"
+            : "/organization/v1/tenants";
+        const idHeader = this.getIdHeader();
+        let page = 1;
+        let totalPages = 1;
+        while (page <= totalPages) {
+            const token = await this.tokenManager.getToken();
+            const url = new URL(`${SOPHOS_GLOBAL_API}${apiPath}`);
+            url.searchParams.set("page", String(page));
+            if (page === 1) {
+                url.searchParams.set("pageTotal", "true");
+            }
+            const response = await fetch(url.toString(), {
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    [idHeader.name]: idHeader.value,
+                },
+            });
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new Error(`List tenants failed (${response.status}): ${errorText}`);
+            }
+            const data = (await response.json());
+            if (page === 1 && data.pages.total) {
+                totalPages = data.pages.total;
+            }
+            for (const tenant of data.items) {
+                this.tenantCache.set(tenant.id, {
+                    id: tenant.id,
+                    name: tenant.name,
+                    apiHost: tenant.apiHost,
+                    dataRegion: tenant.dataRegion,
+                    dataGeography: tenant.dataGeography,
+                });
+            }
+            page++;
+        }
+        this.tenantsLoaded = true;
+        console.error(`[sophos-tenant] Loaded ${this.tenantCache.size} tenants`);
+        return Array.from(this.tenantCache.values());
+    }
+    /**
+     * Resolves a tenant ID to its API host. Loads tenants if not cached.
+     */
+    async resolveApiHost(tenantId) {
+        if (this.tenantCache.has(tenantId)) {
+            return this.tenantCache.get(tenantId).apiHost;
+        }
+        // Try loading tenants if we haven't yet
+        if (!this.tenantsLoaded) {
+            await this.loadTenants();
+        }
+        const info = this.tenantCache.get(tenantId);
+        if (!info) {
+            throw new Error(`Tenant ${tenantId} not found. Use sophos_list_tenants to see available tenants.`);
+        }
+        return info.apiHost;
+    }
+    /**
+     * Returns the tenant ID to use. For single-tenant callers, returns the
+     * identity ID. For partner/org callers, requires an explicit tenant ID.
+     */
+    resolveTenantId(providedTenantId) {
+        const identity = this.getIdentity();
+        if (identity.idType === "tenant") {
+            return providedTenantId || identity.id;
+        }
+        if (!providedTenantId) {
+            throw new Error("tenant_id is required for partner/organization callers. " +
+                "Use sophos_list_tenants to find available tenant IDs.");
+        }
+        return providedTenantId;
+    }
+    /**
+     * Returns all cached tenants.
+     */
+    getCachedTenants() {
+        return Array.from(this.tenantCache.values());
+    }
+}
+//# sourceMappingURL=tenant-resolver.js.map