@finctl/mcp 0.1.0

package/README.md

@@ -0,0 +1,224 @@
+# @finctl/mcp
+
+FinCtl's [Model Context Protocol](https://modelcontextprotocol.io) server. Exposes AWS
+cost intelligence — spend summaries, top services, savings recommendations, rightsizing,
+forecasts, anomalies, and account info — directly inside AI-assisted dev tools (Cursor,
+VS Code Copilot, Kiro, Claude Code, and any MCP-compatible client).
+
+> **Status:** all 10 tools return live data from the FinCtl backend when an endpoint is
+> configured (FIN-1467/1468/1469). Without an endpoint, each cost tool returns a clear
+> "not configured" message.
+
+## Install & run
+
+```bash
+export FINCTL_API_KEY=fct_live_xxxx   # required
+npx @finctl/mcp                       # stdio transport, no install
+```
+
+Or install globally:
+
+```bash
+npm install -g @finctl/mcp
+finctl-mcp --version
+```
+
+### CLI options
+
+```
+finctl-mcp [options]
+
+  --http               Run the HTTP/SSE transport instead of stdio
+  --port <n>           HTTP port (default 3000; or PORT env)
+  --endpoint <url>     FinCtl backend base URL (or FINCTL_ENDPOINT env)
+  -v, --version        Print version and exit
+  -h, --help           Print usage and exit
+```
+
+`--version` and `--help` work without an API key; starting the server requires
+`FINCTL_API_KEY`.
+
+### From source
+
+```bash
+npm install
+npm run build && node dist/index.js   # stdio
+npm run dev                           # stdio, no build (tsx)
+npm run dev:http                      # HTTP/SSE on :3000
+```
+
+## IDE integrations
+
+| Tool | Guide |
+| ---- | ----- |
+| Cursor | [docs/integrations/cursor.md](docs/integrations/cursor.md) |
+| Claude Code | [docs/integrations/claude-code.md](docs/integrations/claude-code.md) |
+| Cline / Roo Code | [docs/integrations/cline.md](docs/integrations/cline.md) |
+| Amazon Q Developer | [docs/integrations/amazon-q.md](docs/integrations/amazon-q.md) |
+| VS Code (GitHub Copilot) | [docs/integrations/vscode.md](docs/integrations/vscode.md) |
+| Kiro | [docs/integrations/kiro.md](docs/integrations/kiro.md) |
+| Continue.dev | [docs/integrations/continue.md](docs/integrations/continue.md) |
+| Windsurf | [docs/integrations/windsurf.md](docs/integrations/windsurf.md) |
+| JetBrains AI Assistant | [docs/integrations/jetbrains.md](docs/integrations/jetbrains.md) |
+| OpenAI Codex CLI | [docs/integrations/codex.md](docs/integrations/codex.md) |
+| Raycast | [docs/integrations/raycast.md](docs/integrations/raycast.md) |
+
+Verify every tool is callable end-to-end (the same round-trip an IDE performs):
+
+```bash
+FINCTL_API_KEY=your-key npm run validate
+```
+
+## Transports
+
+| Transport | Command | Used by |
+| -- | -- | -- |
+| **stdio** | `finctl-mcp` (default) | Local IDE integrations — the client spawns the process and speaks JSON-RPC over stdin/stdout. |
+| **HTTP/SSE** | `finctl-mcp --http [--port N]` | Hosted/remote connections and web MCP clients. Uses the Streamable HTTP transport (carries server→client messages as Server-Sent Events). |
+
+The HTTP server exposes:
+
+- `POST /mcp` — MCP endpoint (stateless)
+- `GET /health` — liveness check
+
+For a hosted endpoint on AWS (Docker + ECS Fargate behind an ALB, SSE-tuned), see
+[docs/deployment/aws.md](docs/deployment/aws.md). For the per-customer (one
+isolated AWS account each) deploy runbook, see
+[docs/deployment/per-customer-deployment.md](docs/deployment/per-customer-deployment.md).
+Quick local container run:
+
+```bash
+docker build -t finctl-mcp .
+docker run --rm -p 3000:3000 -e FINCTL_API_KEY=fct_live_xxxx finctl-mcp
+```
+
+## Tool catalog
+
+| Tool | Description |
+| -- | -- |
+| `get_cost_summary` | Total spend, top accounts, top services |
+| `list_top_services` | Top services by cost |
+| `get_recommendations` | Active savings recommendations |
+| `get_rightsizing` | EC2/RDS rightsizing opportunities |
+| `get_resource_details` | One resource's type, account, active recommendations |
+| `get_forecast` | Projected spend, growth, budget variance |
+| `get_anomalies` | Recent cost anomalies, sorted by severity |
+| `get_budget_status` | Budgets: spend, % consumed, projected, on-track |
+| `list_accounts` | Linked AWS accounts |
+| `get_savings_plans_coverage` | RI/SP coverage and waste |
+
+Tool definitions (names, descriptions, input schemas) live in
+[`src/tools/catalog.ts`](src/tools/catalog.ts). Adding a tool = adding one entry there.
+
+## Project structure
+
+```
+finctl-mcp/
+├── package.json
+├── tsconfig.json
+├── README.md
+├── scripts/
+│   └── smoke.mjs             # build-time smoke test (version, handshake, tool list)
+├── .github/workflows/        # CI (build + test) and Publish (on version tag)
+└── src/
+    ├── index.ts              # entrypoint — flags + transport selection
+    ├── version.ts            # runtime version (reads package.json)
+    ├── server.ts             # builds the McpServer, registers the catalog
+    ├── auth/                 # API key validation, scoping, rate limiting
+    ├── client/
+    │   └── finctl-client.ts  # HTTP client for the FinCtl backend
+    ├── tools/
+    │   └── catalog.ts        # tool definitions + handlers
+    └── transports/
+        ├── stdio.ts          # local IDE transport
+        └── http.ts           # hosted Streamable HTTP/SSE transport
+```
+
+## Publishing
+
+CI (`.github/workflows`) builds and runs the smoke test on every push/PR. Pushing a
+version tag publishes to npm:
+
+```bash
+npm version patch        # bump package.json + create vX.Y.Z tag
+git push --follow-tags   # CI publishes @finctl/mcp on the tag
+```
+
+The publish workflow verifies the tag matches `package.json`, runs build + test, then
+`npm publish --provenance --access public`. Requires an `NPM_TOKEN` repo secret with
+publish rights to the `@finctl` scope — see
+[docs/deployment/npm-publishing.md](docs/deployment/npm-publishing.md) for one-time token
+setup and the release steps.
+
+> Stretch (not yet done): Homebrew tap (`brew install finctl/tap/finctl-mcp`) and
+> automated changelog generation.
+
+## Verifying the handshake
+
+```bash
+# stdio: send an initialize request and read the response (key required)
+printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"0"}}}' \
+  | FINCTL_API_KEY=fct_test_local node dist/index.js
+```
+
+## Authentication
+
+Every request authenticates with a per-customer API key. The key resolves to a customer
+ID and account scope; all tool responses carry that scope, so a customer only ever sees
+their own data.
+
+| Transport | How the key is passed |
+| -- | -- |
+| stdio | `FINCTL_API_KEY` environment variable (one customer per process; missing/invalid key fails fast at startup) |
+| HTTP | `Authorization: Bearer <key>` header (validated per request) |
+
+Invalid or missing keys are rejected before reaching the MCP layer (JSON-RPC error
+`-32001`, HTTP 401). Each key is rate-limited (default 60 req/min, JSON-RPC `-32002`,
+HTTP 429).
+
+### Configuration (env)
+
+| Var | Purpose | Default |
+| -- | -- | -- |
+| `FINCTL_API_KEY` | Active API key | — (required) |
+| `FINCTL_CUSTOMER_ID` | Customer the key maps to | `local` |
+| `FINCTL_ACCOUNT_IDS` | Comma-separated AWS account scope (empty = all customer accounts) | — |
+| `FINCTL_RATE_LIMIT` | Requests per minute per key | `60` |
+| `FINCTL_API_KEY_PREVIOUS` | Prior key, accepted during rotation grace | — |
+| `FINCTL_API_KEY_PREVIOUS_EXPIRES_AT` | Epoch ms after which the prior key is rejected | — |
+
+**Zero-downtime rotation:** set the new key as `FINCTL_API_KEY`, the old one as
+`FINCTL_API_KEY_PREVIOUS`, and `FINCTL_API_KEY_PREVIOUS_EXPIRES_AT` to ~5 min out. Both
+keys work until the old one expires.
+
+## Backend connection
+
+The cost tools proxy to the FinCtl backend (the `dashboard-api` Lambda in `finctl-core`)
+rather than querying AWS directly. Point the server at a backend:
+
+| Var | Purpose |
+| -- | -- |
+| `FINCTL_ENDPOINT` (or `FINCTL_DASHBOARD_API_URL`) | Backend base URL. Without it, cost tools return a clear "not configured" error. |
+| `FINCTL_MCP_SERVICE_SECRET` | Shared service secret (= backend `MCP_VALIDATE_SECRET`). Authenticates the MCP server to the backend. |
+| `FINCTL_BACKEND_TOKEN` | Optional Cognito Bearer token, if a deployment uses one. |
+
+Each request forwards `X-Finctl-Mcp-Secret: <FINCTL_MCP_SERVICE_SECRET>` and
+`X-Customer-Id: <customerId>` (resolved from the caller's API key) so the backend
+authenticates and scopes the data (FIN-2648). Endpoints used:
+`/api/accounts`, `/api/accounts/spend-summary`, `/api/resources/top-cost`,
+`/api/recommendations`, `/api/org/sp-utilization`, `/api/org/ri-utilization`,
+`/api/forecast`, `/api/anomalies`, `/api/budgets`.
+
+### Key store
+
+Key validation goes through a pluggable [`KeyStore`](src/auth/store.ts) interface:
+
+- **`BackendKeyStore`** (production) — when `FINCTL_ENDPOINT` + `FINCTL_MCP_SERVICE_SECRET`
+  are set, presented keys are validated against the backend's
+  `POST /api/mcp-keys/validate` (FIN-2646), which resolves the customer scope from the
+  portal-generated key records. Positive results are cached ~60s.
+- **`EnvKeyStore`** (local/dev) — used when no backend is configured; validates a single
+  `FINCTL_API_KEY` from the env (see the table above), with rotation grace.
+
+Customer-facing key generation/revocation lives in the FinCtl backend + portal UI
+(FIN-1475); this repo consumes those keys.

package/dist/auth/authenticator.d.ts

@@ -0,0 +1,37 @@
+import type { AuthContext } from "./context.js";
+import { type KeyStore } from "./store.js";
+import { type RateLimiter } from "./rate-limit.js";
+export type AuthErrorCode = "unauthorized" | "rate_limited";
+/** Authentication/authorization failure, mapped to a JSON-RPC error by callers. */
+export declare class AuthError extends Error {
+    readonly code: AuthErrorCode;
+    constructor(code: AuthErrorCode, message: string);
+}
+/**
+ * Validates a presented API key and enforces per-key rate limiting, producing
+ * the {@link AuthContext} that scopes a request to one customer.
+ */
+export declare class Authenticator {
+    private readonly store;
+    private readonly limiter;
+    constructor(store: KeyStore, limiter: RateLimiter);
+    authenticate(presentedKey: string | undefined): Promise<AuthContext>;
+}
+/**
+ * Build the default authenticator from environment configuration:
+ * an {@link EnvKeyStore} plus a 60 req/min per-key limiter.
+ *
+ *   FINCTL_RATE_LIMIT          requests per minute per key (default 60)
+ *
+ * Store selection: when a backend endpoint and the shared MCP service secret are
+ * configured, keys are validated against the backend (production — customers'
+ * portal-generated keys live there). Otherwise an env-backed key is used for
+ * local dev.
+ *
+ *   FINCTL_ENDPOINT | FINCTL_DASHBOARD_API_URL   backend base URL
+ *   FINCTL_MCP_SERVICE_SECRET                    = backend MCP_VALIDATE_SECRET
+ */
+export declare function createAuthenticator(env?: NodeJS.ProcessEnv): {
+    authenticator: Authenticator;
+    store: KeyStore;
+};

package/dist/auth/authenticator.js

@@ -0,0 +1,66 @@
+import { EnvKeyStore } from "./store.js";
+import { BackendKeyStore } from "./backend-store.js";
+import { FixedWindowRateLimiter } from "./rate-limit.js";
+/** Authentication/authorization failure, mapped to a JSON-RPC error by callers. */
+export class AuthError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "AuthError";
+    }
+}
+/**
+ * Validates a presented API key and enforces per-key rate limiting, producing
+ * the {@link AuthContext} that scopes a request to one customer.
+ */
+export class Authenticator {
+    store;
+    limiter;
+    constructor(store, limiter) {
+        this.store = store;
+        this.limiter = limiter;
+    }
+    async authenticate(presentedKey) {
+        if (!presentedKey) {
+            throw new AuthError("unauthorized", "Missing API key");
+        }
+        const validation = await this.store.validate(presentedKey);
+        if (!validation) {
+            throw new AuthError("unauthorized", "Invalid API key");
+        }
+        if (!this.limiter.allow(validation.keyId)) {
+            throw new AuthError("rate_limited", "Rate limit exceeded");
+        }
+        return {
+            keyId: validation.keyId,
+            customerId: validation.customerId,
+            accountIds: validation.accountIds,
+        };
+    }
+}
+/**
+ * Build the default authenticator from environment configuration:
+ * an {@link EnvKeyStore} plus a 60 req/min per-key limiter.
+ *
+ *   FINCTL_RATE_LIMIT          requests per minute per key (default 60)
+ *
+ * Store selection: when a backend endpoint and the shared MCP service secret are
+ * configured, keys are validated against the backend (production — customers'
+ * portal-generated keys live there). Otherwise an env-backed key is used for
+ * local dev.
+ *
+ *   FINCTL_ENDPOINT | FINCTL_DASHBOARD_API_URL   backend base URL
+ *   FINCTL_MCP_SERVICE_SECRET                    = backend MCP_VALIDATE_SECRET
+ */
+export function createAuthenticator(env = process.env) {
+    const baseUrl = (env.FINCTL_ENDPOINT || env.FINCTL_DASHBOARD_API_URL)?.trim();
+    const serviceSecret = env.FINCTL_MCP_SERVICE_SECRET?.trim();
+    const store = baseUrl && serviceSecret
+        ? new BackendKeyStore({ baseUrl, serviceSecret })
+        : new EnvKeyStore(env);
+    const limit = Number(env.FINCTL_RATE_LIMIT) || 60;
+    const authenticator = new Authenticator(store, new FixedWindowRateLimiter(limit));
+    return { authenticator, store };
+}
+//# sourceMappingURL=authenticator.js.map

package/dist/auth/authenticator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authenticator.js","sourceRoot":"","sources":["../../src/auth/authenticator.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAiB,MAAM,YAAY,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,sBAAsB,EAAoB,MAAM,iBAAiB,CAAC;AAI3E,mFAAmF;AACnF,MAAM,OAAO,SAAU,SAAQ,KAAK;IAEvB;IADX,YACW,IAAmB,EAC5B,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QAHN,SAAI,GAAJ,IAAI,CAAe;QAI5B,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,aAAa;IAEL;IACA;IAFnB,YACmB,KAAe,EACf,OAAoB;QADpB,UAAK,GAAL,KAAK,CAAU;QACf,YAAO,GAAP,OAAO,CAAa;IACpC,CAAC;IAEJ,KAAK,CAAC,YAAY,CAAC,YAAgC;QACjD,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,MAAM,IAAI,SAAS,CAAC,cAAc,EAAE,iBAAiB,CAAC,CAAC;QACzD,CAAC;QACD,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;QAC3D,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,MAAM,IAAI,SAAS,CAAC,cAAc,EAAE,iBAAiB,CAAC,CAAC;QACzD,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;YAC1C,MAAM,IAAI,SAAS,CAAC,cAAc,EAAE,qBAAqB,CAAC,CAAC;QAC7D,CAAC;QACD,OAAO;YACL,KAAK,EAAE,UAAU,CAAC,KAAK;YACvB,UAAU,EAAE,UAAU,CAAC,UAAU;YACjC,UAAU,EAAE,UAAU,CAAC,UAAU;SAClC,CAAC;IACJ,CAAC;CACF;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAyB,OAAO,CAAC,GAAG;IAItE,MAAM,OAAO,GAAG,CAAC,GAAG,CAAC,eAAe,IAAI,GAAG,CAAC,wBAAwB,CAAC,EAAE,IAAI,EAAE,CAAC;IAC9E,MAAM,aAAa,GAAG,GAAG,CAAC,yBAAyB,EAAE,IAAI,EAAE,CAAC;IAC5D,MAAM,KAAK,GACT,OAAO,IAAI,aAAa;QACtB,CAAC,CAAC,IAAI,eAAe,CAAC,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC;QACjD,CAAC,CAAC,IAAI,WAAW,CAAC,GAAG,CAAC,CAAC;IAE3B,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,iBAAiB,CAAC,IAAI,EAAE,CAAC;IAClD,MAAM,aAAa,GAAG,IAAI,aAAa,CAAC,KAAK,EAAE,IAAI,sBAAsB,CAAC,KAAK,CAAC,CAAC,CAAC;IAClF,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC;AAClC,CAAC"}

package/dist/auth/backend-store.d.ts

@@ -0,0 +1,19 @@
+import { type KeyStore, type KeyValidation } from "./store.js";
+export interface BackendKeyStoreOptions {
+    baseUrl: string;
+    /** Shared service secret (sent as X-Finctl-Mcp-Secret; = backend MCP_VALIDATE_SECRET). */
+    serviceSecret: string;
+    cacheTtlMs?: number;
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}
+export declare class BackendKeyStore implements KeyStore {
+    private readonly baseUrl;
+    private readonly serviceSecret;
+    private readonly cacheTtlMs;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    private readonly cache;
+    constructor(opts: BackendKeyStoreOptions);
+    validate(presentedKey: string): Promise<KeyValidation | null>;
+}

package/dist/auth/backend-store.js

@@ -0,0 +1,57 @@
+import { keyId } from "./store.js";
+export class BackendKeyStore {
+    baseUrl;
+    serviceSecret;
+    cacheTtlMs;
+    timeoutMs;
+    fetchImpl;
+    cache = new Map();
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+        this.serviceSecret = opts.serviceSecret;
+        this.cacheTtlMs = opts.cacheTtlMs ?? 60_000;
+        this.timeoutMs = opts.timeoutMs ?? 10_000;
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+    }
+    async validate(presentedKey) {
+        const id = keyId(presentedKey);
+        const cached = this.cache.get(id);
+        if (cached && cached.expiresAt > Date.now())
+            return cached.validation;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        let res;
+        try {
+            res = await this.fetchImpl(`${this.baseUrl}/api/mcp-keys/validate`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Accept: "application/json",
+                    "X-Finctl-Mcp-Secret": this.serviceSecret,
+                },
+                body: JSON.stringify({ key: presentedKey }),
+                signal: controller.signal,
+            });
+        }
+        catch {
+            // Network/timeout — treat as not-valid (caller surfaces an auth error).
+            return null;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!res.ok)
+            return null; // 401 = invalid/revoked key
+        const data = (await res.json());
+        if (!data.customerId)
+            return null;
+        const validation = {
+            keyId: id,
+            customerId: data.customerId,
+            accountIds: data.accountIds ?? [],
+        };
+        this.cache.set(id, { validation, expiresAt: Date.now() + this.cacheTtlMs });
+        return validation;
+    }
+}
+//# sourceMappingURL=backend-store.js.map

package/dist/auth/backend-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend-store.js","sourceRoot":"","sources":["../../src/auth/backend-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAqC,MAAM,YAAY,CAAC;AAyBtE,MAAM,OAAO,eAAe;IACT,OAAO,CAAS;IAChB,aAAa,CAAS;IACtB,UAAU,CAAS;IACnB,SAAS,CAAS;IAClB,SAAS,CAAe;IACxB,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;IAEvD,YAAY,IAA4B;QACtC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAChD,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,aAAa,CAAC;QACxC,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,MAAM,CAAC;QAC5C,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,MAAM,CAAC;QAC1C,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,KAAK,CAAC;IAC3C,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,YAAoB;QACjC,MAAM,EAAE,GAAG,KAAK,CAAC,YAAY,CAAC,CAAC;QAE/B,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAClC,IAAI,MAAM,IAAI,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE;YAAE,OAAO,MAAM,CAAC,UAAU,CAAC;QAEtE,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QACnE,IAAI,GAAa,CAAC;QAClB,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,OAAO,wBAAwB,EAAE;gBAClE,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE;oBACP,cAAc,EAAE,kBAAkB;oBAClC,MAAM,EAAE,kBAAkB;oBAC1B,qBAAqB,EAAE,IAAI,CAAC,aAAa;iBAC1C;gBACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,EAAE,YAAY,EAAE,CAAC;gBAC3C,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC,CAAC;QACL,CAAC;QAAC,MAAM,CAAC;YACP,wEAAwE;YACxE,OAAO,IAAI,CAAC;QACd,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;QAED,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,OAAO,IAAI,CAAC,CAAC,4BAA4B;QACtD,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAmD,CAAC;QAClF,IAAI,CAAC,IAAI,CAAC,UAAU;YAAE,OAAO,IAAI,CAAC;QAElC,MAAM,UAAU,GAAkB;YAChC,KAAK,EAAE,EAAE;YACT,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,UAAU,EAAE,IAAI,CAAC,UAAU,IAAI,EAAE;SAClC,CAAC;QACF,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,UAAU,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;QAC5E,OAAO,UAAU,CAAC;IACpB,CAAC;CACF"}

package/dist/auth/context.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The authenticated caller's scope. Resolved from an API key and made available
+ * to every tool handler so responses can be filtered to this customer's data —
+ * no cross-customer leakage.
+ */
+export interface AuthContext {
+    /** Stable, non-secret identifier for the key (safe to log). */
+    keyId: string;
+    /** Customer the key belongs to. All data queries filter by this. */
+    customerId: string;
+    /** AWS accounts this key may read. Empty = all of the customer's accounts. */
+    accountIds: string[];
+}
+export declare function setProcessAuth(ctx: AuthContext | null): void;
+/** Run `fn` with `ctx` as the active auth context (used per-request by HTTP). */
+export declare function runWithAuth<T>(ctx: AuthContext, fn: () => T): T;
+/** Current auth context, or null if none is active. */
+export declare function currentAuthOrNull(): AuthContext | null;
+/**
+ * Current auth context. Throws if none is active — tool handlers must never run
+ * unauthenticated, so this throwing is a safety net, not normal control flow.
+ */
+export declare function currentAuth(): AuthContext;

package/dist/auth/context.js

@@ -0,0 +1,30 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const als = new AsyncLocalStorage();
+/**
+ * Process-wide fallback context. The stdio transport serves a single customer
+ * per process, so it sets this once at startup rather than wrapping every
+ * incoming message. HTTP uses {@link runWithAuth} per request instead.
+ */
+let processDefault = null;
+export function setProcessAuth(ctx) {
+    processDefault = ctx;
+}
+/** Run `fn` with `ctx` as the active auth context (used per-request by HTTP). */
+export function runWithAuth(ctx, fn) {
+    return als.run(ctx, fn);
+}
+/** Current auth context, or null if none is active. */
+export function currentAuthOrNull() {
+    return als.getStore() ?? processDefault;
+}
+/**
+ * Current auth context. Throws if none is active — tool handlers must never run
+ * unauthenticated, so this throwing is a safety net, not normal control flow.
+ */
+export function currentAuth() {
+    const ctx = currentAuthOrNull();
+    if (!ctx)
+        throw new Error("No authentication context — request reached a tool handler unauthenticated");
+    return ctx;
+}
+//# sourceMappingURL=context.js.map

package/dist/auth/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/auth/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAgBrD,MAAM,GAAG,GAAG,IAAI,iBAAiB,EAAe,CAAC;AAEjD;;;;GAIG;AACH,IAAI,cAAc,GAAuB,IAAI,CAAC;AAE9C,MAAM,UAAU,cAAc,CAAC,GAAuB;IACpD,cAAc,GAAG,GAAG,CAAC;AACvB,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,WAAW,CAAI,GAAgB,EAAE,EAAW;IAC1D,OAAO,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AAC1B,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,iBAAiB;IAC/B,OAAO,GAAG,CAAC,QAAQ,EAAE,IAAI,cAAc,CAAC;AAC1C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW;IACzB,MAAM,GAAG,GAAG,iBAAiB,EAAE,CAAC;IAChC,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,4EAA4E,CAAC,CAAC;IACxG,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/auth/rate-limit.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Per-key fixed-window rate limiter. In-memory — fine for a single stdio process
+ * and per-instance HTTP throttling. A hosted multi-instance deployment (FIN-1474)
+ * should swap this for a shared store (e.g. Redis/DynamoDB) behind the same
+ * {@link RateLimiter} interface.
+ */
+export interface RateLimiter {
+    /** Record one request for `key`; return false if it exceeds the limit. */
+    allow(key: string): boolean;
+}
+export declare class FixedWindowRateLimiter implements RateLimiter {
+    private readonly limit;
+    private readonly windowMs;
+    private readonly windows;
+    constructor(limit?: number, windowMs?: number);
+    allow(key: string): boolean;
+}

package/dist/auth/rate-limit.js

@@ -0,0 +1,22 @@
+export class FixedWindowRateLimiter {
+    limit;
+    windowMs;
+    windows = new Map();
+    constructor(limit = 60, windowMs = 60_000) {
+        this.limit = limit;
+        this.windowMs = windowMs;
+    }
+    allow(key) {
+        const now = Date.now();
+        const win = this.windows.get(key);
+        if (!win || now >= win.resetAt) {
+            this.windows.set(key, { count: 1, resetAt: now + this.windowMs });
+            return true;
+        }
+        if (win.count >= this.limit)
+            return false;
+        win.count++;
+        return true;
+    }
+}
+//# sourceMappingURL=rate-limit.js.map

package/dist/auth/rate-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.js","sourceRoot":"","sources":["../../src/auth/rate-limit.ts"],"names":[],"mappings":"AAgBA,MAAM,OAAO,sBAAsB;IAId;IACA;IAJF,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IAErD,YACmB,QAAQ,EAAE,EACV,WAAW,MAAM;QADjB,UAAK,GAAL,KAAK,CAAK;QACV,aAAQ,GAAR,QAAQ,CAAS;IACjC,CAAC;IAEJ,KAAK,CAAC,GAAW;QACf,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAElC,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;YAC/B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,GAAG,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;YAClE,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,GAAG,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK;YAAE,OAAO,KAAK,CAAC;QAC1C,GAAG,CAAC,KAAK,EAAE,CAAC;QACZ,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/auth/store.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Resolved scope for a valid API key. Backends (env, DynamoDB, SSM) all produce
+ * this shape so the rest of the server is storage-agnostic.
+ */
+export interface KeyValidation {
+    /** Stable, non-secret key identifier — safe to log and rate-limit on. */
+    keyId: string;
+    customerId: string;
+    /** AWS accounts the key may read. Empty = all of the customer's accounts. */
+    accountIds: string[];
+}
+/**
+ * Pluggable API key store. Production will back this with DynamoDB or SSM (key
+ * lookup → customer scope); see {@link EnvKeyStore} for the local/dev impl.
+ */
+export interface KeyStore {
+    /** Return the key's scope if valid, else null. Constant-time on the secret. */
+    validate(presentedKey: string): Promise<KeyValidation | null>;
+}
+/**
+ * Derive a stable, non-secret identifier from a key. Logging the raw key would
+ * leak a credential; this hash prefix is safe to log and rate-limit on.
+ */
+export declare function keyId(key: string): string;
+/**
+ * Env-var-backed key store for local/dev and stdio single-customer processes.
+ *
+ *   FINCTL_API_KEY                       active key (required)
+ *   FINCTL_CUSTOMER_ID                   customer the key maps to (default "local")
+ *   FINCTL_ACCOUNT_IDS                   comma-separated AWS account scope (optional)
+ *
+ * Zero-downtime rotation grace — the previous key keeps working until its expiry
+ * (default 5 minutes after rotation):
+ *   FINCTL_API_KEY_PREVIOUS              prior key, still accepted during grace
+ *   FINCTL_API_KEY_PREVIOUS_EXPIRES_AT   epoch ms after which the prior key is rejected
+ */
+export declare class EnvKeyStore implements KeyStore {
+    private readonly current;
+    private readonly previous;
+    private readonly previousExpiresAt;
+    private readonly customerId;
+    private readonly accountIds;
+    constructor(env?: NodeJS.ProcessEnv);
+    /** True if at least one key is configured (used to fail fast at startup). */
+    isConfigured(): boolean;
+    validate(presentedKey: string): Promise<KeyValidation | null>;
+}

package/dist/auth/store.js

@@ -0,0 +1,62 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+/**
+ * Derive a stable, non-secret identifier from a key. Logging the raw key would
+ * leak a credential; this hash prefix is safe to log and rate-limit on.
+ */
+export function keyId(key) {
+    return "k_" + createHash("sha256").update(key).digest("hex").slice(0, 12);
+}
+/** Length-safe, timing-safe key comparison. */
+function secretEquals(a, b) {
+    const ab = Buffer.from(a);
+    const bb = Buffer.from(b);
+    if (ab.length !== bb.length)
+        return false;
+    return timingSafeEqual(ab, bb);
+}
+/**
+ * Env-var-backed key store for local/dev and stdio single-customer processes.
+ *
+ *   FINCTL_API_KEY                       active key (required)
+ *   FINCTL_CUSTOMER_ID                   customer the key maps to (default "local")
+ *   FINCTL_ACCOUNT_IDS                   comma-separated AWS account scope (optional)
+ *
+ * Zero-downtime rotation grace — the previous key keeps working until its expiry
+ * (default 5 minutes after rotation):
+ *   FINCTL_API_KEY_PREVIOUS              prior key, still accepted during grace
+ *   FINCTL_API_KEY_PREVIOUS_EXPIRES_AT   epoch ms after which the prior key is rejected
+ */
+export class EnvKeyStore {
+    current;
+    previous;
+    previousExpiresAt;
+    customerId;
+    accountIds;
+    constructor(env = process.env) {
+        this.current = env.FINCTL_API_KEY?.trim() || undefined;
+        this.previous = env.FINCTL_API_KEY_PREVIOUS?.trim() || undefined;
+        this.previousExpiresAt = Number(env.FINCTL_API_KEY_PREVIOUS_EXPIRES_AT) || 0;
+        this.customerId = env.FINCTL_CUSTOMER_ID?.trim() || "local";
+        this.accountIds = (env.FINCTL_ACCOUNT_IDS ?? "")
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean);
+    }
+    /** True if at least one key is configured (used to fail fast at startup). */
+    isConfigured() {
+        return Boolean(this.current);
+    }
+    async validate(presentedKey) {
+        const scope = { customerId: this.customerId, accountIds: this.accountIds };
+        if (this.current && secretEquals(presentedKey, this.current)) {
+            return { keyId: keyId(this.current), ...scope };
+        }
+        if (this.previous &&
+            this.previousExpiresAt > Date.now() &&
+            secretEquals(presentedKey, this.previous)) {
+            return { keyId: keyId(this.previous), ...scope };
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/auth/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/auth/store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAuB1D;;;GAGG;AACH,MAAM,UAAU,KAAK,CAAC,GAAW;IAC/B,OAAO,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC5E,CAAC;AAED,+CAA+C;AAC/C,SAAS,YAAY,CAAC,CAAS,EAAE,CAAS;IACxC,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC1B,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC1B,IAAI,EAAE,CAAC,MAAM,KAAK,EAAE,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC1C,OAAO,eAAe,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,WAAW;IACL,OAAO,CAAqB;IAC5B,QAAQ,CAAqB;IAC7B,iBAAiB,CAAS;IAC1B,UAAU,CAAS;IACnB,UAAU,CAAW;IAEtC,YAAY,MAAyB,OAAO,CAAC,GAAG;QAC9C,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC,cAAc,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC;QACvD,IAAI,CAAC,QAAQ,GAAG,GAAG,CAAC,uBAAuB,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC;QACjE,IAAI,CAAC,iBAAiB,GAAG,MAAM,CAAC,GAAG,CAAC,kCAAkC,CAAC,IAAI,CAAC,CAAC;QAC7E,IAAI,CAAC,UAAU,GAAG,GAAG,CAAC,kBAAkB,EAAE,IAAI,EAAE,IAAI,OAAO,CAAC;QAC5D,IAAI,CAAC,UAAU,GAAG,CAAC,GAAG,CAAC,kBAAkB,IAAI,EAAE,CAAC;aAC7C,KAAK,CAAC,GAAG,CAAC;aACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;aACpB,MAAM,CAAC,OAAO,CAAC,CAAC;IACrB,CAAC;IAED,6EAA6E;IAC7E,YAAY;QACV,OAAO,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,YAAoB;QACjC,MAAM,KAAK,GAAG,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC;QAE3E,IAAI,IAAI,CAAC,OAAO,IAAI,YAAY,CAAC,YAAY,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YAC7D,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,GAAG,KAAK,EAAE,CAAC;QAClD,CAAC;QACD,IACE,IAAI,CAAC,QAAQ;YACb,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC,GAAG,EAAE;YACnC,YAAY,CAAC,YAAY,EAAE,IAAI,CAAC,QAAQ,CAAC,EACzC,CAAC;YACD,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,GAAG,KAAK,EAAE,CAAC;QACnD,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}