forta-mcp 1.0.0 → 1.1.0

package/AGENTS.md

@@ -0,0 +1,202 @@
+# AGENTS.md — forta-mcp
+
+> `forta-mcp` is the **Model Context Protocol server for Forta**, the OAuth2 identity provider
+> for `appleby.cloud`. It exposes the `forta-api` admin surface to Claude Code as **25 typed
+> tools** — users, platforms, roles, grants, token introspection and API tokens. This file
+> orients any agent/worker before touching code in this repo.
+>
+> **⚠️ Golden rule — keep this file current:** any change that adds, removes or retypes a tool,
+> or drifts from `forta-api`'s routes, MUST update this AGENTS.md in the SAME change.
+>
+> **⚠️ Blast radius:** these tools can delete users, delete platforms and rotate client
+> secrets. `forta_rotate_platform_credentials` takes a platform *down* until its deployed config
+> is updated. Tool descriptions are the only warning an agent gets — keep them honest.
+
+---
+
+## What this repo is
+
+A single-file Node ESM program (`index.js`) speaking MCP over stdio, translating tool calls into
+HTTP requests against `forta-api` at **`auth.appleby.cloud`**. Published to npm as `forta-mcp`,
+consumed via `npx -y forta-mcp`.
+
+It owns only the translation layer — tool names, argument schemas, descriptions, URL
+construction. All behaviour comes from `forta-api`.
+
+Its reason to exist: Forta is the identity provider for the whole ecosystem, so nearly every
+auth bug starts there. `forta_list_grants` turns "why is this user getting a 403 from Keyring"
+from a manual database dig into one call.
+
+## Stack & dependencies
+
+- **Node ≥18** (global `fetch`, `AbortSignal.timeout`). `"type": "module"`, top-level `await`.
+- **`@modelcontextprotocol/sdk` ^1.29.0**, **`zod`** (transitive via the SDK — not declared).
+- No build step, no tests, no linter. `node --check index.js` is the only static gate.
+
+## Project structure
+
+| Path | Role |
+|------|------|
+| `index.js` | `--setup` flow, config guard, `api()`/`text()`/`body()` helpers, all 25 tools, transport. |
+| `package.json` | `bin.forta-mcp` → `index.js`. |
+| `README.md` | User-facing setup + tool tables. |
+| `AGENTS.md` | This file. |
+
+## Running, building & testing
+
+```bash
+npm install
+node --check index.js
+node index.js --setup                                    # writes ~/.mcp.json
+FORTA_API_URL=... FORTA_API_TOKEN=frt_... node index.js   # run on stdio
+```
+
+Smoke test without a client (the `sleep`s are required — requests otherwise race the handshake):
+
+```bash
+{ echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}'
+  sleep 2
+  echo '{"jsonrpc":"2.0","method":"notifications/initialized"}'
+  echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
+  sleep 2; } | FORTA_API_URL=x FORTA_API_TOKEN=frt_x node index.js
+```
+
+## How code is written here
+
+- **Every tool follows one shape** — `server.tool(name, description, zodSchema, handler)`, and
+  the handler ends `return { content: text(res) }`.
+- **Naming:** `forta_` prefix, then verb, then noun.
+- **`api(method, path, params, body, opts)`** — `params` become query entries (undefined/null
+  dropped); `body` is JSON by default. `opts.form` switches to
+  `application/x-www-form-urlencoded`; `opts.noAuth` omits the `Authorization` header. **Both
+  exist solely for `/oauth/introspect`** — see below.
+- **`body(obj)` strips `undefined`.** Always use it on PUT tools: `forta-api` treats a
+  present-but-null field as an explicit clear, so forwarding raw `{...fields}` would wipe every
+  field the caller omitted.
+- **Descriptions carry the blast radius.** Anything destructive must say so and name the safer
+  alternative.
+
+### Sensitive value masking
+
+`api()` passes every decoded JSON response through **`sanitise()`** before returning it. This is
+central, not per-tool, so a newly added tool is safe by default rather than by remembering.
+
+`mask()` keeps a value's **first two characters** and appends a **fixed-width tail** —
+`"supersecret"` → `"su**********"`. The prefix is what makes the mask useful rather than merely
+safe: you can still tell one credential from another, or confirm a rotation actually changed a
+value. The tail is fixed width so the mask does not disclose the real length. Values under
+three characters are masked whole, so a two-character secret cannot round-trip as itself.
+
+The same shape is implemented in all five `*-mcp` servers.
+
+`SECRET_FIELDS` covers `client_secret`, `secret`, `password`, `token`, `api_token`,
+`access_token`, `refresh_token`, `id_token`, `oauth_request_token`, `plaintext`, `private_key`
+and `signing_key`, masked at **any nesting depth**, in objects and arrays alike.
+
+This matters most on the three tools that mint a credential and return it exactly once:
+`forta_create_platform` and `forta_rotate_platform_credentials` (a `client_secret`) and
+`forta_create_api_token` (a plaintext `frt_` token). Those are keys to the whole SSO estate.
+Introspection metadata — `active`, `sub`, `exp`, `token_type` — is deliberately left readable,
+since that is the entire point of `forta_introspect_token`.
+
+`FORTA_ALLOW_SECRET_VALUES=1` disables masking. It is off by default and should stay that way;
+read a real credential from the Forta dashboard instead.
+
+## Domain & architecture
+
+**Auth.** One long-lived `frt_` API token in `FORTA_API_TOKEN`, sent as
+`Authorization: Bearer` on every request. `/admin/*` additionally requires the owning user to
+be a Forta **super-admin** — the token does not bypass that.
+
+**Tool groups:**
+
+| Group | Tools |
+|-------|-------|
+| Health & identity | `forta_health`, `forta_get_self` |
+| Users | list, get, update, delete |
+| Platforms | list, get, create, update, delete, rotate credentials |
+| Roles | list, get, create, update, delete |
+| Grants | list, create, revoke, check |
+| Tokens | introspect, list/create/revoke API tokens |
+
+### Two behaviours that are easy to get wrong
+
+**1. `/oauth/introspect` is a resource-server endpoint, not an admin one.** It requires the
+*calling platform's* `client_id` and `client_secret`, reads **form-encoded** parameters, and
+ignores the `Authorization` header entirely. It also only understands access JWTs — an opaque
+`frt_` token reports `active: false`, which reads as "revoked" but means "wrong tool"
+(`forta_list_api_tokens` is the right one). Introspection is scoped to the calling platform, so
+a token valid elsewhere returns `active: false`.
+
+The original implementation sent JSON with no credentials and **returned `invalid_client` on
+every call** — it never worked. `opts.form` and `opts.noAuth` exist because of this.
+
+**2. `/admin/grants` filters are mutually exclusive.** `HandleAdminListGrants` selects with a
+`switch`, so passing both `platform_id` and `user_id` silently drops `user_id`. The tool
+description says so; do not "fix" it by sending both.
+
+## Ecosystem & related repos
+
+| Repo | Relationship |
+|------|--------------|
+| [`forta-api`](https://github.com/aidenappl/forta-api) | The API this wraps. Its `main.go` is the source of truth for coverage. |
+| [`go-forta`](https://github.com/aidenappl/go-forta) | v1.3.0+ accepts the `frt_` tokens this server uses. |
+| [`keyring-mcp`](https://github.com/aidenappl/keyring-mcp) | **Uses the same `frt_` token** — Keyring has no admin credential of its own. |
+| `lattice-mcp`, `monitor-mcp`, `openbucket-mcp` | Sibling MCPs; keep the single-file structure aligned. |
+
+## Operations
+
+- **Published to npm** as `forta-mcp` (public). `npx -y` resolves the latest, so **publishing
+  is deployment**.
+- **Publishing requires 2FA via passkey** and must run from an interactive terminal — npm's web
+  auth flow needs a browser, and from a non-TTY subprocess it degrades to demanding an OTP a
+  passkey-only account cannot produce.
+- **A running MCP server does not pick up a new npm version** — the client must restart.
+- **Common failure modes:**
+  - *All tools `fetch failed`* — wrong `FORTA_API_URL`. The API is **`auth.appleby.cloud`**;
+    `forta.appleby.cloud` is the dashboard and returns 404 on `/healthcheck`.
+  - *All tools 401* — token revoked or expired.
+  - *`/admin` tools 403 but `forta_get_self` works* — the owning user is not super-admin.
+
+## Rules & guardrails
+
+- **Never hardcode a token, URL or hostname.**
+- **Never log request or response bodies.** `forta_create_api_token` and
+  `forta_create_platform` return live secrets exactly once.
+- **Never weaken `sanitise()`.** It must stay recursive, applied centrally in `api()`, and on by
+  default. If something genuinely needs a real value, the answer is
+  `FORTA_ALLOW_SECRET_VALUES=1` in that server's env, not an exemption in the code.
+- **Never add a tool without reading its handler in `forta-api`.** Struct fields are not the
+  request contract — that assumption is exactly what shipped the broken introspect tool.
+- **Never rename an existing tool.** Names are a public contract; add and deprecate instead.
+- **`zod` is used but not declared** in `package.json`, resolving transitively through the MCP
+  SDK. Declaring it explicitly is the right fix, as a standalone change.
+- Publishing is outward-facing and effectively irreversible (npm unpublish is restricted after
+  72 hours) — do not publish without explicit instruction.
+
+## Verification — always before "done"
+
+```bash
+node --check index.js
+grep -c 'server.tool(' index.js      # expect 25
+```
+
+Then the stdio handshake above, asserting the server starts with **no stderr**, the tool count
+is right, and there are **no duplicate names** — `server.tool` accepts duplicates silently, the
+last registration wins, and the earlier tool vanishes without an error.
+
+For any tool added or changed, make **one real call against the live API**. Schema checks catch
+typos; they do not catch wrong units, wrong enum values, wrong content types, or parameters the
+handler ignores — every bug this repo has shipped was in that second category.
+
+**Never report work complete on the strength of `tools/list` alone.**
+
+## Keeping this file updated
+
+Update this AGENTS.md in the same change when you:
+- **Add/remove/rename a tool** → update the group table and the count in the header.
+- **Change `api()` or its `opts`** → update *How code is written here*.
+- **Discover a `forta-api` behaviour that contradicts a tool description** → fix both, and
+  record it under *Two behaviours that are easy to get wrong* if it is non-obvious.
+- **Publish** → note the version and what changed.
+- Also keep `README.md`'s tool tables in sync.

package/README.md

@@ -46,6 +46,24 @@ curl -X POST https://auth.appleby.cloud/admin/api-tokens \
 
 Tokens are `frt_`-prefixed, owned by the creating user, and require that user to be a Forta super-admin for the `/admin` tools. The plaintext is returned once and stored only as a SHA-256 hash.
 
+## Secret values are masked
+
+Every response is passed through a masking step before it reaches the model. Anything that looks
+like a credential keeps its **first two characters** and loses the rest to a fixed-width tail —
+`supersecret` becomes `su**********`.
+
+That is enough to tell two credentials apart, or to confirm a rotation actually changed
+something, and not enough to use. The tail is a fixed width so the mask does not reveal the real
+length.
+
+This matters most on the tools that mint a credential and return it exactly once —
+`forta_create_platform` and `forta_rotate_platform_credentials` (a `client_secret`) and
+`forta_create_api_token` (a plaintext `frt_` token). Read the real value from the Forta
+dashboard instead. Introspection metadata (`active`, `sub`, `exp`, `token_type`) is left
+readable.
+
+Set `FORTA_ALLOW_SECRET_VALUES=1` to turn masking off if you genuinely need a working value.
+
 ## Tools
 
 ### Health & identity

package/index.js

@@ -62,9 +62,54 @@ if (!API_URL || !API_TOKEN) {
     process.exit(1);
 }
 
+// --- Sensitive value masking ---
+//
+// Several Forta endpoints return a live credential exactly once, at the moment
+// it is minted: forta_create_platform and forta_rotate_platform_credentials
+// return a client_secret, forta_create_api_token returns a plaintext frt_
+// token. Those are the keys to the whole SSO estate, and anything that reaches
+// a model's context is in a transcript forever.
+//
+// Sensitive values are masked to their first two characters plus a
+// fixed-width tail: "frt_abc123" -> "fr**********". The prefix keeps a value
+// identifiable and comparable while the fixed tail avoids disclosing length.
+// Read the usable value from the Forta dashboard instead.
+//
+// Set FORTA_ALLOW_SECRET_VALUES=1 to pass values through unmasked.
+
+const ALLOW_SECRETS = process.env.FORTA_ALLOW_SECRET_VALUES === "1";
+
+function mask(value) {
+    if (typeof value !== "string" || value === "") return value;
+    // Under three characters there is no prefix worth keeping — a two-char
+    // secret would otherwise round-trip as itself.
+    if (value.length < 3) return "**********";
+    return value.slice(0, 2) + "**********";
+}
+
+// Response fields that are a credential wherever they appear. `id_token` and
+// `access_token` are included because the OAuth endpoints return real, usable
+// session tokens.
+const SECRET_FIELDS = new Set([
+    "client_secret", "secret", "password", "token", "api_token", "access_token",
+    "refresh_token", "id_token", "oauth_request_token", "plaintext",
+    "private_key", "signing_key",
+]);
+
+// Walks a decoded response and masks every sensitive value in place.
+function sanitise(node) {
+    if (ALLOW_SECRETS || node === null || typeof node !== "object") return node;
+    if (Array.isArray(node)) return node.map(sanitise);
+    const out = {};
+    for (const [k, v] of Object.entries(node)) {
+        out[k] = SECRET_FIELDS.has(k) && typeof v === "string" ? mask(v) : sanitise(v);
+    }
+    return out;
+}
+
 // --- HTTP helper ---
 
-async function api(method, path, params, body) {
+async function api(method, path, params, body, opts_ = {}) {
     const url = new URL(path, API_URL);
     if (params) {
         for (const [k, v] of Object.entries(params)) {
@@ -73,12 +118,16 @@ async function api(method, path, params, body) {
     }
     const opts = {
         method,
-        headers: {
-            Authorization: `Bearer ${API_TOKEN}`,
-        },
+        headers: {},
         signal: AbortSignal.timeout(30000),
     };
-    if (body) {
+    // The OAuth endpoints authenticate with client credentials, not the API
+    // token, and reject a stray Authorization header.
+    if (!opts_.noAuth) opts.headers.Authorization = `Bearer ${API_TOKEN}`;
+    if (body && opts_.form) {
+        opts.headers["Content-Type"] = "application/x-www-form-urlencoded";
+        opts.body = new URLSearchParams(body).toString();
+    } else if (body) {
         opts.headers["Content-Type"] = "application/json";
         opts.body = JSON.stringify(body);
     }
@@ -87,7 +136,7 @@ async function api(method, path, params, body) {
         const text = await res.text();
         if (!text) return { success: res.ok, status: res.status };
         try {
-            return JSON.parse(text);
+            return sanitise(JSON.parse(text));
         } catch {
             // /healthcheck and the OAuth endpoints return bare text, not the envelope.
             return { success: res.ok, status: res.status, body: text };
@@ -109,7 +158,7 @@ function body(obj) {
 
 const server = new McpServer({
     name: "forta",
-    version: "1.0.0",
+    version: "1.1.0",
 });
 
 // --- Health & identity ---
@@ -279,9 +328,9 @@ server.tool("forta_delete_role", "Delete a role. Users holding it lose its permi
 
 // --- Grants ---
 
-server.tool("forta_list_grants", "List access grants — which users can access which platforms, and with what role. Filter by platform_id or user_id; omit both to list all. This is the first place to look when a user gets a 403 from an appleby.cloud service", {
-    platform_id: z.number().optional().describe("Filter to one platform"),
-    user_id: z.number().optional().describe("Filter to one user"),
+server.tool("forta_list_grants", "List access grants — which users can access which platforms, and with what role. The first place to look when a user gets a 403 from an appleby.cloud service. Filters are mutually exclusive, not combined: pass platform_id OR user_id, or neither to list all. Passing both silently ignores user_id", {
+    platform_id: z.number().optional().describe("Filter to one platform (takes precedence over user_id)"),
+    user_id: z.number().optional().describe("Filter to one user (ignored if platform_id is also given)"),
 }, async ({ platform_id, user_id }) => {
     const res = await api("GET", "/admin/grants", { platform_id, user_id });
     return { content: text(res) };
@@ -312,10 +361,13 @@ server.tool("forta_check_grant", "Check whether the token's user holds an active
 
 // --- Token introspection ---
 
-server.tool("forta_introspect_token", "Introspect an access token (RFC 7662) — returns active, sub, exp, iat, client_id, token_type. Use this to diagnose whether a token a service rejected is expired, malformed, or bound to a different platform", {
-    token: z.string().describe("The access token to introspect"),
-}, async ({ token }) => {
-    const res = await api("POST", "/oauth/introspect", null, { token });
+server.tool("forta_introspect_token", "Introspect an access JWT (RFC 7662) — returns active, sub, exp, iat, token_type. Answers 'is the token this service rejected expired, malformed, or lacking a grant?'. Requires the calling platform's client credentials: introspection is scoped to that platform, and a token valid elsewhere returns active=false here. Only works for access JWTs — opaque frt_ API tokens always report active=false, so use forta_list_api_tokens to inspect those instead", {
+    token: z.string().describe("The access JWT to introspect"),
+    client_id: z.string().describe("Calling platform's client_id (from forta_list_platforms)"),
+    client_secret: z.string().describe("Calling platform's client_secret — shown only when the platform is created or its credentials are rotated"),
+}, async ({ token, client_id, client_secret }) => {
+    const res = await api("POST", "/oauth/introspect", null,
+        { token, client_id, client_secret }, { form: true, noAuth: true });
     return { content: text(res) };
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forta-mcp",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "MCP server for the Forta OAuth2 identity provider",
   "type": "module",
   "main": "index.js",
@@ -13,7 +13,10 @@
   "keywords": [
     "mcp",
     "forta",
-    "auth", "oauth", "identity", "sso",
+    "auth",
+    "oauth",
+    "identity",
+    "sso",
     "model-context-protocol"
   ],
   "author": "Aiden Appleby",