@clavex/mcp-server 1.0.0

package/src/tools/pam.ts

@@ -0,0 +1,285 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { getClient } from "../client.js";
+import { handleError, mdTable } from "../helpers.js";
+
+export function registerPAMTools(server: McpServer): void {
+  // ── List pending PAM access requests ──────────────────────────────────────
+  server.registerTool(
+    "clavex_pam_list_pending",
+    {
+      title: "List Pending PAM Access Requests",
+      description: `List all pending Privileged Access Management (PAM) JIT access requests for an organization.
+
+Returns: id, resource_name, resource_type, justification, requested_duration (minutes), created_at.
+
+A security engineer approves or denies these using clavex_pam_approve.
+
+Use when:
+  "show pending PAM requests"
+  "chi ha richiesto accesso privilegiato?"
+  "which JIT access requests need approval?"
+  "list all open privileged access requests"`,
+      inputSchema: {
+        org_id: z.string().uuid().describe("Organization UUID"),
+      },
+      annotations: { readOnlyHint: true, destructiveHint: false },
+    },
+    async ({ org_id }) =>
+      handleError(async () => {
+        const resp = await getClient().get<{ data: Array<Record<string, unknown>> }>(
+          getClient().orgPath(org_id, "/pam/access-requests?status=pending"),
+        );
+        const items = resp.data ?? [];
+        if (!Array.isArray(items) || items.length === 0) {
+          return "_No pending PAM access requests._";
+        }
+        return mdTable(items, [
+          "id",
+          "resource_name",
+          "resource_type",
+          "justification",
+          "requested_duration",
+          "created_at",
+        ]);
+      }),
+  );
+
+  // ── Submit a JIT access request ────────────────────────────────────────────
+  server.registerTool(
+    "clavex_pam_request",
+    {
+      title: "Request Privileged Access (PAM JIT)",
+      description: `Submit a Just-In-Time (JIT) privileged access request to the PAM system.
+
+The request is routed to the security team for approval.
+Once approved, access is active for the requested duration and automatically revoked when it expires.
+
+Args:
+  - org_id: Organization UUID
+  - resource_name: Human-readable name of the resource (e.g. "prod-db", "k8s-prod-cluster")
+  - resource_type: Category — "database" | "server" | "kubernetes" | "api" | "generic"
+  - resource_id: Unique identifier (hostname, ARN, UUID, etc.)
+  - justification: Why access is needed — be specific (e.g. "deploy hotfix for incident #1234")
+  - duration_minutes: Requested access window in minutes (5–480, default 60)
+
+Returns: Created access request JSON — save the id to approve/track it.
+
+Use when:
+  "richiedi accesso privilegiato al database prod per 2 ore"
+  "request 120-minute access to prod-db — hotfix deploy"
+  "submit a PAM JIT request for the Kubernetes cluster"`,
+      inputSchema: {
+        org_id:           z.string().uuid().describe("Organization UUID"),
+        resource_name:    z.string().describe("Human-readable resource name, e.g. 'prod-db'"),
+        resource_type:    z
+          .enum(["database", "server", "kubernetes", "api", "generic"])
+          .default("generic")
+          .describe("Resource category"),
+        resource_id:      z.string().describe("Unique resource identifier (hostname, ARN, UUID, etc.)"),
+        justification:    z
+          .string()
+          .min(10)
+          .describe("Reason for access — be specific, e.g. 'deploy hotfix for incident #1234'"),
+        duration_minutes: z
+          .number()
+          .int()
+          .min(5)
+          .max(480)
+          .default(60)
+          .describe("Requested access window in minutes (5–480, default 60)"),
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+    },
+    async ({ org_id, resource_name, resource_type, resource_id, justification, duration_minutes }) =>
+      handleError(async () => {
+        const req = await getClient().post<Record<string, unknown>>(
+          getClient().orgPath(org_id, "/pam/access-requests"),
+          {
+            resource_name,
+            resource_type,
+            resource_id,
+            justification,
+            requested_duration: duration_minutes,
+          },
+        );
+        return [
+          `PAM access request submitted — status: **pending**`,
+          ``,
+          `\`\`\`json`,
+          JSON.stringify(req, null, 2),
+          `\`\`\``,
+          ``,
+          `Awaiting security team approval.`,
+          `Use \`clavex_pam_approve\` with \`request_id: "${req["id"]}"\` to approve or deny.`,
+        ].join("\n");
+      }),
+  );
+
+  // ── Approve or deny a PAM access request ──────────────────────────────────
+  server.registerTool(
+    "clavex_pam_approve",
+    {
+      title: "Approve or Deny PAM Access Request",
+      description: `Approve or deny a pending Privileged Access Management (PAM) JIT access request.
+
+Approving activates access for the originally requested duration, then auto-revokes it.
+Denying rejects the request; the requester cannot use that access window.
+
+Use clavex_pam_list_pending first to get the request IDs awaiting decision.
+
+Args:
+  - org_id: Organization UUID
+  - request_id: UUID of the PAM access request to decide on
+  - decision: "approve" or "deny"
+  - note (optional): Message visible to the requester (reason for approval or denial)
+
+Returns: Updated access request JSON — status becomes "active" (approved) or "denied".
+
+Use when:
+  "approva la richiesta PAM <id>"
+  "approve prod-db request for Alice — confirmed maintenance window"
+  "deny PAM request — not an approved change window"
+  "nega la richiesta di accesso privilegiato"`,
+      inputSchema: {
+        org_id:     z.string().uuid().describe("Organization UUID"),
+        request_id: z.string().uuid().describe("PAM access request UUID"),
+        decision:   z.enum(["approve", "deny"]).describe('"approve" = grant access, "deny" = reject'),
+        note:       z.string().optional().describe("Optional note to the requester"),
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+    },
+    async ({ org_id, request_id, decision, note }) =>
+      handleError(async () => {
+        const endpoint = decision === "approve" ? "approve" : "deny";
+        const result = await getClient().post<Record<string, unknown>>(
+          getClient().orgPath(org_id, `/pam/access-requests/${request_id}/${endpoint}`),
+          { note: note ?? "" },
+        );
+        const emoji = decision === "approve" ? "✅" : "❌";
+        const label = decision === "approve" ? "APPROVED — access is now active" : "DENIED";
+        return [
+          `${emoji} Request \`${request_id}\`: **${label}**`,
+          ``,
+          `\`\`\`json`,
+          JSON.stringify(result, null, 2),
+          `\`\`\``,
+        ].join("\n");
+      }),
+  );
+
+  // ── Vault: list credentials ────────────────────────────────────────────────
+  server.registerTool(
+    "clavex_vault_list_credentials",
+    {
+      title: "Vault: List Credentials",
+      description: `List all credentials stored in the PAM vault for an organization.
+
+Returns: id, name, credential_type, username, target_host, checkout_duration, require_access_request, is_active.
+Note: plaintext secrets are never returned in list responses. Use clavex_vault_checkout to retrieve a secret.
+
+Use when:
+  "show vault credentials"
+  "which credentials are in the PAM vault?"
+  "quali credenziali ci sono nel vault?"
+  "list SSH keys in the vault"`,
+      inputSchema: {
+        org_id: z.string().uuid().describe("Organization UUID"),
+      },
+      annotations: { readOnlyHint: true, destructiveHint: false },
+    },
+    async ({ org_id }) =>
+      handleError(async () => {
+        const resp = await getClient().get<{ data: Array<Record<string, unknown>> }>(
+          getClient().orgPath(org_id, "/pam/credentials"),
+        );
+        const items = resp.data ?? [];
+        if (!Array.isArray(items) || items.length === 0) {
+          return "_No vault credentials found._";
+        }
+        return mdTable(items, [
+          "id",
+          "name",
+          "credential_type",
+          "username",
+          "target_host",
+          "checkout_duration",
+          "require_access_request",
+          "is_active",
+        ]);
+      }),
+  );
+
+  // ── Vault: checkout credential ─────────────────────────────────────────────
+  server.registerTool(
+    "clavex_vault_checkout",
+    {
+      title: "Vault: Checkout Credential",
+      description: `Check out a credential from the Clavex PAM vault. Returns the plaintext secret once.
+
+The credential is locked for the checkout duration and automatically released when it expires.
+Pass an approved access_request_id when the credential policy requires one.
+
+⚠️  The secret is returned ONCE — store it immediately.
+    It will NOT be shown again and access is revoked after the checkout window closes.
+
+Args:
+  - org_id: Organization UUID
+  - cred_id: UUID of the vault credential (from clavex_vault_list_credentials)
+  - reason (optional): Reason for checkout (goes to audit trail)
+  - access_request_id (optional): UUID of an approved PAM access request (required if credential policy demands it)
+
+Returns:
+  - secret: plaintext credential — save immediately
+  - checkout: metadata including expires_at and checkout_id
+
+Use when:
+  "checkout prod-db password from vault"
+  "ritira le credenziali SSH dalla vault"
+  "get the API key for prod deployment — linked to request <id>"`,
+      inputSchema: {
+        org_id:            z.string().uuid().describe("Organization UUID"),
+        cred_id:           z
+          .string()
+          .uuid()
+          .describe("Vault credential UUID (use clavex_vault_list_credentials to find)"),
+        reason:            z
+          .string()
+          .optional()
+          .describe("Reason for checkout — recorded in the audit trail"),
+        access_request_id: z
+          .string()
+          .uuid()
+          .optional()
+          .describe("Approved PAM access request UUID (required when credential policy demands it)"),
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+    },
+    async ({ org_id, cred_id, reason, access_request_id }) =>
+      handleError(async () => {
+        const body: Record<string, unknown> = {};
+        if (reason)            body["reason"] = reason;
+        if (access_request_id) body["access_request_id"] = access_request_id;
+
+        const result = await getClient().post<{
+          checkout: Record<string, unknown>;
+          secret:   string;
+          warning:  string;
+        }>(
+          getClient().orgPath(org_id, `/pam/credentials/${cred_id}/checkout`),
+          body,
+        );
+
+        return [
+          `⚠️  **${result.warning}**`,
+          ``,
+          `**Secret:** \`${result.secret}\``,
+          ``,
+          `**Checkout details:**`,
+          `\`\`\`json`,
+          JSON.stringify(result.checkout, null, 2),
+          `\`\`\``,
+        ].join("\n");
+      }),
+  );
+}

package/src/tools/policies.ts

@@ -0,0 +1,233 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { getClient } from "../client.js";
+import { handleError, mdTable } from "../helpers.js";
+
+export function registerPolicyTools(server: McpServer): void {
+  // ── List policies ──────────────────────────────────────────────────────────
+  server.registerTool(
+    "clavex_list_policies",
+    {
+      title: "List Auth Policies",
+      description: `List all auth-flow policy rules for an organization.
+
+Rules are evaluated in priority order (lowest number first) on every login attempt.
+Each rule matches conditions (country, IP range, device, time) and applies an action (allow, deny, require_mfa).
+
+Returns: id, name, priority, action, conditions summary, is_active.
+
+Use when: "show auth policies for org <id>", "what geo-blocking rules are active?".`,
+      inputSchema: {
+        org_id: z.string().uuid().describe("Organization UUID"),
+      },
+      annotations: { readOnlyHint: true, destructiveHint: false },
+    },
+    async ({ org_id }) =>
+      handleError(async () => {
+        const rules = await getClient().get<Array<Record<string, unknown>>>(
+          getClient().orgPath(org_id, "/auth-policies"),
+        );
+        return mdTable(rules, ["id", "name", "priority", "action", "is_active"]);
+      }),
+  );
+
+  // ── Create policy ──────────────────────────────────────────────────────────
+  server.registerTool(
+    "clavex_create_policy",
+    {
+      title: "Create Auth Policy Rule",
+      description: `Create a new auth-flow policy rule for an organization.
+
+Rules control login behavior: blocking countries, requiring MFA, restricting IP ranges.
+Rules are evaluated in priority order — lower number = evaluated first.
+
+Args:
+  - org_id: Organization UUID
+  - name: Rule name (e.g. "Block Russia")
+  - priority: Evaluation order (1 = first). Rules with same priority are evaluated in creation order.
+  - action: What to do when rule matches:
+      "allow"        — permit login (use to create allow-list exceptions before a deny rule)
+      "deny"         — block login
+      "require_mfa"  — force MFA step
+  - conditions: JSON object describing match criteria. Supported fields:
+      { "country": ["US", "DE"] }          — match these countries
+      { "country_not": ["RU", "CN"] }      — block these countries
+      { "ip_cidr": ["10.0.0.0/8"] }        — match IP ranges
+      { "ip_cidr_not": ["..."] }           — exclude IP ranges
+      { "user_group": ["<group_id>"] }     — match users in group
+      Conditions are ANDed together.
+  - description (optional): Human-readable explanation
+
+Returns: Created policy rule JSON.
+
+Examples:
+  - "block all logins from Russia" → action=deny, conditions={"country":["RU"]}
+  - "require MFA for everyone" → action=require_mfa, conditions={}`,
+      inputSchema: {
+        org_id:      z.string().uuid().describe("Organization UUID"),
+        name:        z.string().describe("Rule name"),
+        priority:    z.number().int().min(1).describe("Evaluation order (lower = first)"),
+        action:      z.enum(["allow", "deny", "require_mfa"]).describe("Action when rule matches"),
+        conditions:  z.record(z.unknown()).describe("Match conditions JSON object"),
+        description: z.string().optional().describe("Human-readable explanation"),
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+    },
+    async ({ org_id, name, priority, action, conditions, description }) =>
+      handleError(async () => {
+        const rule = await getClient().post<Record<string, unknown>>(
+          getClient().orgPath(org_id, "/auth-policies"),
+          { name, priority, action, conditions, description },
+        );
+        return `Policy rule created:\n\n${JSON.stringify(rule, null, 2)}`;
+      }),
+  );
+
+  // ── Delete policy ──────────────────────────────────────────────────────────
+  server.registerTool(
+    "clavex_delete_policy",
+    {
+      title: "Delete Auth Policy Rule",
+      description: `Delete an auth-flow policy rule. Logins previously affected by this rule will no longer be restricted by it.
+
+Use when: "remove policy rule <id>", "delete the block-russia rule".`,
+      inputSchema: {
+        org_id:  z.string().uuid().describe("Organization UUID"),
+        rule_id: z.string().uuid().describe("Policy rule UUID"),
+      },
+      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
+    },
+    async ({ org_id, rule_id }) =>
+      handleError(async () => {
+        await getClient().del(getClient().orgPath(org_id, `/auth-policies/${rule_id}`));
+        return `Policy rule ${rule_id} deleted.`;
+      }),
+  );
+
+  // ── Simulate policy ────────────────────────────────────────────────────────
+  server.registerTool(
+    "clavex_simulate_policy",
+    {
+      title: "Simulate Auth Policy Evaluation",
+      description: `Dry-run the auth policy evaluation for a hypothetical login — no actual login occurs.
+
+Useful for testing policy rules: "would this user be blocked if logging in from Russia?"
+
+Args:
+  - org_id: Organization UUID
+  - user_id (optional): UUID of the user whose groups/attributes to consider
+  - ip_address (optional): Simulated IP address
+  - country (optional): ISO 3166-1 alpha-2 country code (e.g. "RU", "US")
+  - device_type (optional): "mobile" | "desktop"
+
+Returns:
+  - outcome.action: "allow" | "deny" | "require_mfa"
+  - matched_rule: the first rule that matched (or null if no match → default allow)
+  - trace: evaluation trace of all rules checked`,
+      inputSchema: {
+        org_id:      z.string().uuid().describe("Organization UUID"),
+        user_id:     z.string().uuid().optional().describe("User UUID to simulate (considers group memberships)"),
+        ip_address:  z.string().optional().describe("Simulated IP address, e.g. 1.2.3.4"),
+        country:     z.string().length(2).optional().describe("ISO 3166-1 alpha-2 country code, e.g. RU"),
+        device_type: z.enum(["mobile", "desktop"]).optional().describe("Device type"),
+      },
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    },
+    async ({ org_id, user_id, ip_address, country, device_type }) =>
+      handleError(async () => {
+        const body = Object.fromEntries(
+          Object.entries({ user_id, ip_address, country, device_type }).filter(([, v]) => v !== undefined),
+        );
+        const result = await getClient().post<Record<string, unknown>>(
+          getClient().orgPath(org_id, "/auth-policies/simulate"),
+          body,
+        );
+        return JSON.stringify(result, null, 2);
+      }),
+  );
+
+  // ── API Keys ───────────────────────────────────────────────────────────────
+  server.registerTool(
+    "clavex_list_api_keys",
+    {
+      title: "List API Keys",
+      description: `List all superadmin API keys. API keys are used instead of JWT tokens for machine-to-machine integrations.
+
+Returns: id, name, last_used_at, created_at.
+Note: The plaintext secret is never returned after creation.
+
+Use when: "show all API keys", "list service accounts".`,
+      inputSchema: {},
+      annotations: { readOnlyHint: true, destructiveHint: false },
+    },
+    async () =>
+      handleError(async () => {
+        const keys = await getClient().get<Array<Record<string, unknown>>>("/api/v1/admin/api-keys");
+        return mdTable(keys, ["id", "name", "last_used_at", "created_at"]);
+      }),
+  );
+
+  server.registerTool(
+    "clavex_create_api_key",
+    {
+      title: "Create API Key",
+      description: `Create a new superadmin API key for machine-to-machine access.
+
+Returns: API key JSON including the one-time plaintext secret.
+IMPORTANT: Save the secret immediately — it will never be shown again.
+
+Use when: "create API key for Terraform", "generate service account credentials".`,
+      inputSchema: {
+        name: z.string().describe("API key name / description, e.g. 'terraform-provisioner'"),
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+    },
+    async ({ name }) =>
+      handleError(async () => {
+        const result = await getClient().post<Record<string, unknown>>("/api/v1/admin/api-keys", { name });
+        const secret = result.secret ?? result.api_key;
+        return `API key created.\n\n⚠️  SAVE THIS SECRET:\nsecret: ${secret}\n\n${JSON.stringify(result, null, 2)}`;
+      }),
+  );
+
+  server.registerTool(
+    "clavex_delete_api_key",
+    {
+      title: "Delete API Key",
+      description: `Delete a superadmin API key. Any service using it will immediately lose access.
+
+Use when: "revoke API key <id>", "delete the terraform API key".`,
+      inputSchema: {
+        key_id: z.string().uuid().describe("API key UUID"),
+      },
+      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
+    },
+    async ({ key_id }) =>
+      handleError(async () => {
+        await getClient().del(`/api/v1/admin/api-keys/${key_id}`);
+        return `API key ${key_id} deleted.`;
+      }),
+  );
+
+  // ── Usage ──────────────────────────────────────────────────────────────────
+  server.registerTool(
+    "clavex_get_usage",
+    {
+      title: "Get Organization Usage",
+      description: `Get current usage metrics for an organization: active users, sessions, API calls.
+
+Use when: "how many users does org <id> have?", "what's the monthly auth volume?".`,
+      inputSchema: {
+        org_id: z.string().uuid().describe("Organization UUID"),
+      },
+      annotations: { readOnlyHint: true, destructiveHint: false },
+    },
+    async ({ org_id }) =>
+      handleError(async () => {
+        const usage = await getClient().get<Record<string, unknown>>(
+          getClient().orgPath(org_id, "/usage"),
+        );
+        return JSON.stringify(usage, null, 2);
+      }),
+  );
+}

package/src/tools/ssf.ts

@@ -0,0 +1,82 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { getClient } from "../client.js";
+import { handleError, mdTable } from "../helpers.js";
+
+export function registerSSFTools(server: McpServer): void {
+  // ── List SSF streams ───────────────────────────────────────────────────────
+  server.registerTool(
+    "clavex_ssf_list_streams",
+    {
+      title: "List Shared Signals Framework (SSF) Streams",
+      description: `List all Shared Signals Framework (SSF) event delivery streams for an organization.
+
+SSF (OpenID Shared Signals Framework) enables real-time propagation of security events
+(CAEP / RISC) to relying parties — e.g. revoking sessions across all connected apps when
+a user's credentials are compromised.
+
+Stream delivery methods:
+  "push" — Clavex POSTs Security Event Tokens (SETs) to the receiver's endpoint
+  "poll" — The receiver polls Clavex to retrieve queued SETs
+
+Returns: stream_id, delivery_method, endpoint_url, enabled, event_types, last_delivery_status.
+
+Use when:
+  "list SSF streams for org <id>"
+  "which relying parties receive security events?"
+  "mostra i canali di segnalazione eventi di sicurezza"`,
+      inputSchema: {
+        org_id: z.string().uuid().describe("Organization UUID"),
+      },
+      annotations: { readOnlyHint: true, destructiveHint: false },
+    },
+    async ({ org_id }) =>
+      handleError(async () => {
+        const streams = await getClient().get<Array<Record<string, unknown>>>(
+          getClient().orgPath(org_id, "/ssf/streams"),
+        );
+        if (!Array.isArray(streams) || streams.length === 0) {
+          return "_No SSF streams configured for this organization._";
+        }
+        return mdTable(streams, ["id", "delivery_method", "endpoint_url", "enabled", "event_types_requested"]);
+      }),
+  );
+
+  // ── Disable SSF stream ────────────────────────────────────────────────────
+  server.registerTool(
+    "clavex_ssf_disable_stream",
+    {
+      title: "Disable SSF Stream",
+      description: `Disable an SSF event delivery stream so no more SETs are pushed or queued.
+
+Use this to temporarily pause security event delivery without deleting the stream configuration.
+Re-enable by calling the PATCH stream endpoint with enabled=true.
+
+Args:
+  - org_id: Organization UUID
+  - stream_id: UUID of the SSF stream to disable
+
+Use when:
+  "disable SSF stream <id>"
+  "stop sending security events to <endpoint>"
+  "pause event delivery for this relying party"`,
+      inputSchema: {
+        org_id:    z.string().uuid().describe("Organization UUID"),
+        stream_id: z.string().uuid().describe("SSF stream UUID to disable"),
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+    },
+    async ({ org_id, stream_id }) =>
+      handleError(async () => {
+        // The SSF stream is identified by the client (stream is scoped to client credentials).
+        // Admin streams list endpoint returns streams with their IDs.
+        // We use the admin PATCH stream endpoint — stream is identified by the client's stream config.
+        // Since the admin endpoint manages streams by org, we patch using the standard SSF stream API.
+        const result = await getClient().patch<Record<string, unknown>>(
+          getClient().orgPath(org_id, `/ssf/streams/${stream_id}`),
+          { status: "paused" },
+        );
+        return `SSF stream ${stream_id} disabled.\n\n${JSON.stringify(result, null, 2)}`;
+      }),
+  );
+}