forta-mcp 1.0.1 → 1.2.0

package/AGENTS.md

@@ -0,0 +1,225 @@
+# 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. `create`/`update` carry **`backchannel_logout_uri`** — see the warning below |
+| Roles | list, get, create, update, delete |
+| Grants | list, create, revoke, check |
+| Tokens | introspect, list/create/revoke API tokens |
+
+### Setting `backchannel_logout_uri` — order matters
+
+Forta POSTs a signed `logout_token` to this URL the instant a grant is revoked, so the consumer
+ends the session immediately instead of waiting up to five minutes for its introspection poll.
+
+⚠️ **Only set it once the platform actually serves the endpoint.** Until then every notification
+404s, is retried six times on a backoff, and is marked `exhausted` — which looks in the logs like
+a broken receiver rather than one that was never built. Deploy first, register second.
+
+Pass `null` to clear it. Absent is the normal state for a platform that has not implemented the
+receiver, and it is never an error — such a platform is simply skipped by the sender.
+
+`https` only; the emitter refuses anything else at send time and logs
+`FORTA_BACKCHANNEL_BAD_ENDPOINT`.
+
+### 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**.
+- **Bump the version in TWO places before publishing** — `package.json` *and* the `McpServer({
+  version })` literal in `index.js`. npm refuses to republish an existing version, so forgetting
+  `package.json` fails loudly (`cannot publish over the previously published versions`), but
+  forgetting the one in `index.js` fails SILENTLY: the server then reports a version it is not,
+  and a client debugging "which build am I talking to" is misled by the only field that answers
+  that question.
+- **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.
+- **Add/change a tool parameter** → bump the minor version in BOTH places (see *Operations*) in
+  the same change, so the commit that adds the capability is the commit that can be published.
+- **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,6 +62,51 @@ 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, opts_ = {}) {
@@ -91,7 +136,7 @@ async function api(method, path, params, body, opts_ = {}) {
         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 };
@@ -113,7 +158,7 @@ function body(obj) {
 
 const server = new McpServer({
     name: "forta",
-    version: "1.0.0",
+    version: "1.2.0",
 });
 
 // --- Health & identity ---
@@ -188,6 +233,7 @@ server.tool("forta_create_platform", "Register a new OAuth platform. Returns the
     description: z.string().optional().describe("Description"),
     redirect_uris: z.array(z.string()).optional().describe("Allowed OAuth redirect URIs"),
     logout_redirect_uris: z.array(z.string()).optional().describe("Allowed post-logout redirect URIs"),
+    backchannel_logout_uri: z.string().nullable().optional().describe("OIDC Back-Channel Logout 1.0 endpoint on the platform (https only). Forta POSTs a signed logout_token here the moment a grant is revoked, instead of the consumer waiting up to 5 minutes for its introspection poll. Pass null to clear. ⚠️ Only set this once the platform actually serves the endpoint — until then every notification 404s, retries 6 times and is marked exhausted"),
     allowed_origins: z.array(z.string()).optional().describe("Allowed CORS origins"),
     is_first_party: z.boolean().optional().describe("First-party app (skips the consent screen)"),
     internal_resource: z.boolean().optional().describe("Internal resource, hidden from the app launcher"),
@@ -209,6 +255,7 @@ server.tool("forta_update_platform", "Update a platform's configuration. Only th
     platform_type: z.enum(["WEB", "SPA", "SERVICE", "MOBILE"]).optional(),
     redirect_uris: z.array(z.string()).optional(),
     logout_redirect_uris: z.array(z.string()).optional(),
+    backchannel_logout_uri: z.string().nullable().optional().describe("OIDC Back-Channel Logout 1.0 endpoint on the platform (https only). Forta POSTs a signed logout_token here the moment a grant is revoked, instead of the consumer waiting up to 5 minutes for its introspection poll. Pass null to clear. ⚠️ Only set this once the platform actually serves the endpoint — until then every notification 404s, retries 6 times and is marked exhausted"),
     allowed_origins: z.array(z.string()).optional(),
     is_first_party: z.boolean().optional(),
     internal_resource: z.boolean().optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forta-mcp",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "MCP server for the Forta OAuth2 identity provider",
   "type": "module",
   "main": "index.js",