@certynix/mcp 1.0.0

package/src/tools/list-audit-logs.ts

@@ -0,0 +1,76 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import type { CertynixClient } from '@certynix/sdk';
+import { formatError } from '../utils/format.js';
+
+export function registerListAuditLogsTool(server: McpServer, client: CertynixClient): void {
+  server.tool(
+    'list_audit_logs',
+    'Lista o histórico completo de ações auditadas na organização: registros de assets, criação de API Keys, mudanças de plano, alertas, e eventos de segurança.',
+    {
+      limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .optional()
+        .describe('Número de registros por página (máximo 100, padrão 20).'),
+      cursor: z
+        .string()
+        .optional()
+        .describe('Cursor de paginação retornado pela chamada anterior.'),
+      action: z
+        .string()
+        .optional()
+        .describe(
+          'Filtrar por tipo de ação (ex: asset.created, api_key.created, asset.deleted).',
+        ),
+      created_after: z
+        .string()
+        .optional()
+        .describe('Retornar apenas logs criados após esta data (ISO 8601).'),
+      created_before: z
+        .string()
+        .optional()
+        .describe('Retornar apenas logs criados antes desta data (ISO 8601).'),
+    },
+    async (params) => {
+      try {
+        const page = await client.auditLogs.listPage({
+          ...(params.limit !== undefined ? { limit: params.limit } : {}),
+          ...(params.cursor !== undefined ? { cursor: params.cursor } : {}),
+          ...(params.action !== undefined ? { action: params.action } : {}),
+          ...(params.created_after !== undefined ? { createdAfter: params.created_after } : {}),
+          ...(params.created_before !== undefined
+            ? { createdBefore: params.created_before }
+            : {}),
+        });
+
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify(
+                {
+                  data: page.data,
+                  pagination: {
+                    has_more: page.pagination.has_more,
+                    next_cursor: page.pagination.next_cursor,
+                  },
+                  total_returned: page.data.length,
+                },
+                null,
+                2,
+              ),
+            },
+          ],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: 'text' as const, text: formatError(err) }],
+          isError: true,
+        };
+      }
+    },
+  );
+}

package/src/tools/list-webhooks.ts

@@ -0,0 +1,63 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import type { CertynixClient } from '@certynix/sdk';
+import { formatError } from '../utils/format.js';
+
+export function registerListWebhooksTool(server: McpServer, client: CertynixClient): void {
+  server.tool(
+    'list_webhooks',
+    'Lista os endpoints de webhook configurados na organização. O signing_secret nunca é retornado em listagens — apenas o ID e URL são exibidos.',
+    {
+      limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .optional()
+        .describe('Número de webhooks por página (máximo 100, padrão 20).'),
+      cursor: z
+        .string()
+        .optional()
+        .describe('Cursor de paginação retornado pela chamada anterior.'),
+    },
+    async (params) => {
+      try {
+        const page = await client.webhooks.listPage({
+          ...(params.limit !== undefined ? { limit: params.limit } : {}),
+          ...(params.cursor !== undefined ? { cursor: params.cursor } : {}),
+        });
+
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify(
+                {
+                  data: page.data.map((webhook: (typeof page.data)[number]) => ({
+                    id: webhook.id,
+                    url: webhook.url,
+                    events: webhook.events,
+                    // signing_secret NUNCA retornado em listagens
+                    created_at: webhook.createdAt,
+                  })),
+                  pagination: {
+                    has_more: page.pagination.has_more,
+                    next_cursor: page.pagination.next_cursor,
+                  },
+                  total_returned: page.data.length,
+                },
+                null,
+                2,
+              ),
+            },
+          ],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: 'text' as const, text: formatError(err) }],
+          isError: true,
+        };
+      }
+    },
+  );
+}

package/src/tools/register-asset.ts

@@ -0,0 +1,103 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import type { CertynixClient } from '@certynix/sdk';
+import { formatError } from '../utils/format.js';
+
+export function registerRegisterAssetTool(server: McpServer, client: CertynixClient): void {
+  server.tool(
+    'register_asset',
+    'Registra um ativo digital na Certynix. Aceita hash SHA-256, URL pública ou conteúdo de arquivo em base64. Retorna o ID do asset, o hash criptográfico e o URL de verificação pública.',
+    {
+      hash_sha256: z
+        .string()
+        .regex(/^[a-fA-F0-9]{64}$/)
+        .optional()
+        .describe(
+          'Hash SHA-256 do arquivo em formato hexadecimal (64 caracteres). Use quando já calculou o hash localmente.',
+        ),
+      url: z
+        .string()
+        .url()
+        .optional()
+        .describe('URL pública do ativo para calcular e registrar o hash.'),
+      file_base64: z
+        .string()
+        .optional()
+        .describe('Conteúdo do arquivo em base64 (máximo 10MB). Use quando tiver acesso direto ao arquivo.'),
+      filename: z
+        .string()
+        .optional()
+        .describe('Nome original do arquivo (ex: contrato-2024.pdf). Usado para referência — não afeta o hash.'),
+      mime_type: z
+        .string()
+        .optional()
+        .describe('Tipo MIME do arquivo (ex: application/pdf, image/png).'),
+    },
+    async (params) => {
+      try {
+        if (!params.hash_sha256 && !params.url && !params.file_base64) {
+          return {
+            content: [
+              {
+                type: 'text' as const,
+                text: 'Error: one of hash_sha256, url, or file_base64 is required',
+              },
+            ],
+            isError: true,
+          };
+        }
+
+        type RegisterInput = Parameters<typeof client.assets.register>[0];
+        let input: RegisterInput;
+
+        if (params.hash_sha256) {
+          input = {
+            hash_sha256: params.hash_sha256,
+            ...(params.filename !== undefined ? { filename: params.filename } : {}),
+            ...(params.mime_type !== undefined ? { mime_type: params.mime_type } : {}),
+          } as RegisterInput;
+        } else if (params.url) {
+          input = {
+            url: params.url,
+            ...(params.filename !== undefined ? { filename: params.filename } : {}),
+          } as RegisterInput;
+        } else {
+          const buffer = Buffer.from(params.file_base64 as string, 'base64');
+          input = {
+            file: buffer,
+            ...(params.filename !== undefined ? { filename: params.filename } : {}),
+            ...(params.mime_type !== undefined ? { mime_type: params.mime_type } : {}),
+          } as RegisterInput;
+        }
+
+        const asset = await client.assets.register(input);
+
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify(
+                {
+                  id: asset.id,
+                  hash: asset.hash,
+                  status: asset.status,
+                  trust_score: asset.trustScore,
+                  verification_url: `https://certynix.com/verify/${asset.id}`,
+                  is_first_registrant: asset.isFirstRegistrant,
+                  created_at: asset.createdAt,
+                },
+                null,
+                2,
+              ),
+            },
+          ],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: 'text' as const, text: formatError(err) }],
+          isError: true,
+        };
+      }
+    },
+  );
+}

package/src/tools/revoke-api-key.ts

@@ -0,0 +1,65 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import type { CertynixClient } from '@certynix/sdk';
+import { formatError } from '../utils/format.js';
+
+export function registerRevokeApiKeyTool(server: McpServer, client: CertynixClient): void {
+  server.tool(
+    'revoke_api_key',
+    'Revoga uma API Key imediatamente. Todas as integrações que usam esta chave param de funcionar instantaneamente. Esta ação é irreversível — requer confirmação explícita com confirm: true.',
+    {
+      api_key_id: z
+        .string()
+        .min(1)
+        .describe('ID da API Key a ser revogada (retornado pelo list_api_keys).'),
+      confirm: z
+        .literal(true)
+        .describe(
+          'Deve ser true para confirmar a revogação. Esta ação é irreversível e interrompe imediatamente todas as integrações que usam esta chave.',
+        ),
+    },
+    async (params) => {
+      try {
+        // Verificação de segurança adicional além do schema
+        if (params.confirm !== true) {
+          return {
+            content: [
+              {
+                type: 'text' as const,
+                text: 'Error: confirm must be true to revoke an API Key. This action is irreversible and will immediately break all integrations using this key.',
+              },
+            ],
+            isError: true,
+          };
+        }
+
+        await client.apiKeys.revoke(params.api_key_id);
+
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify(
+                {
+                  success: true,
+                  api_key_id: params.api_key_id,
+                  message:
+                    'API Key revogada com sucesso. Todas as integrações que usavam esta chave pararam de funcionar imediatamente.',
+                  warning:
+                    'Esta ação é irreversível. Para reativar o acesso, crie uma nova API Key e atualize todas as integrações.',
+                },
+                null,
+                2,
+              ),
+            },
+          ],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: 'text' as const, text: formatError(err) }],
+          isError: true,
+        };
+      }
+    },
+  );
+}

package/src/tools/verify-asset.ts

@@ -0,0 +1,66 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import type { CertynixClient } from '@certynix/sdk';
+import { formatError } from '../utils/format.js';
+
+export function registerVerifyAssetTool(server: McpServer, client: CertynixClient): void {
+  server.tool(
+    'verify_asset',
+    'Verifica publicamente se um ativo digital é genuíno. Retorna quem certificou o ativo e quando. Esta operação não requer autenticação e não consome quota do plano.',
+    {
+      hash_sha256: z
+        .string()
+        .regex(/^[a-fA-F0-9]{64}$/)
+        .optional()
+        .describe('Hash SHA-256 para verificar (formato hexadecimal, 64 caracteres).'),
+      asset_id: z
+        .string()
+        .optional()
+        .describe('ID do asset retornado pelo register_asset.'),
+    },
+    async (params) => {
+      try {
+        if (!params.hash_sha256 && !params.asset_id) {
+          return {
+            content: [
+              {
+                type: 'text' as const,
+                text: 'Error: one of hash_sha256 or asset_id is required',
+              },
+            ],
+            isError: true,
+          };
+        }
+
+        const result = params.hash_sha256
+          ? await client.verify.byHash(params.hash_sha256)
+          : await client.verify.byAssetId(params.asset_id as string);
+
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify(
+                {
+                  match: result.match,
+                  hash: result.hash,
+                  certifiers: result.certifiers,
+                  summary: result.match
+                    ? `Asset verificado. Certificado por ${result.certifiers.length} organização(ões).`
+                    : 'Asset não encontrado na Certynix.',
+                },
+                null,
+                2,
+              ),
+            },
+          ],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: 'text' as const, text: formatError(err) }],
+          isError: true,
+        };
+      }
+    },
+  );
+}

package/src/tools/verify-webhook-signature.ts

@@ -0,0 +1,232 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+/**
+ * Tolerância máxima de timestamp para prevenir replay attacks.
+ * Conforme especificação: 5 minutos (300 segundos).
+ */
+const MAX_TIMESTAMP_AGE_SECONDS = 300;
+
+/**
+ * Verifica assinatura de webhook localmente via HMAC-SHA256.
+ * NÃO realiza chamada à API — operação 100% local.
+ * NUNCA loga o webhook_secret.
+ */
+export function registerVerifyWebhookSignatureTool(server: McpServer): void {
+  server.tool(
+    'verify_webhook_signature',
+    'Valida se um delivery de webhook é genuíno verificando a assinatura HMAC-SHA256. Operação local — não realiza chamada à API. Use para garantir que o evento veio da Certynix e não foi adulterado. Proteção anti-replay: timestamps com mais de 5 minutos são rejeitados.',
+    {
+      payload: z
+        .string()
+        .min(1)
+        .describe('Body raw do webhook recebido (string exata, sem parsing JSON prévio).'),
+      signature: z
+        .string()
+        .min(1)
+        .describe(
+          'Valor do header X-Certynix-Signature recebido (formato esperado: t=timestamp,v1=hash).',
+        ),
+      webhook_secret: z
+        .string()
+        .min(1)
+        .describe(
+          'Signing secret do webhook (obtido ao criar o webhook via create_webhook). Este valor nunca aparecerá no output.',
+        ),
+    },
+    (params) => {
+      // NUNCA logar webhook_secret — nem em debug, nem em erro
+      try {
+        const signatureHeader = params.signature;
+
+        // Extrair timestamp e assinatura do header
+        // Formato: t=1706745600,v1=abc123def456...
+        const parts = signatureHeader.split(',');
+        let timestamp: string | undefined;
+        let receivedSignature: string | undefined;
+
+        for (const part of parts) {
+          if (part.startsWith('t=')) {
+            timestamp = part.slice(2);
+          } else if (part.startsWith('v1=')) {
+            receivedSignature = part.slice(3);
+          }
+        }
+
+        if (!timestamp || !receivedSignature) {
+          return {
+            content: [
+              {
+                type: 'text' as const,
+                text: JSON.stringify(
+                  {
+                    valid: false,
+                    error:
+                      "Invalid signature header format. Expected: t=<timestamp>,v1=<hash>. Got: " +
+                      signatureHeader.substring(0, 50),
+                  },
+                  null,
+                  2,
+                ),
+              },
+            ],
+          };
+        }
+
+        // Validar que o timestamp é numérico
+        const timestampNumber = parseInt(timestamp, 10);
+        if (isNaN(timestampNumber)) {
+          return {
+            content: [
+              {
+                type: 'text' as const,
+                text: JSON.stringify(
+                  {
+                    valid: false,
+                    error: 'Invalid timestamp in signature header: not a number.',
+                  },
+                  null,
+                  2,
+                ),
+              },
+            ],
+          };
+        }
+
+        // Verificar anti-replay: timestamp não pode ser mais antigo que 5 minutos
+        const nowSeconds = Math.floor(Date.now() / 1000);
+        const ageSeconds = nowSeconds - timestampNumber;
+
+        if (ageSeconds > MAX_TIMESTAMP_AGE_SECONDS) {
+          return {
+            content: [
+              {
+                type: 'text' as const,
+                text: JSON.stringify(
+                  {
+                    valid: false,
+                    error: `Replay attack detected: timestamp is ${ageSeconds} seconds old (maximum allowed: ${MAX_TIMESTAMP_AGE_SECONDS} seconds).`,
+                    timestamp_age_seconds: ageSeconds,
+                  },
+                  null,
+                  2,
+                ),
+              },
+            ],
+          };
+        }
+
+        if (ageSeconds < -60) {
+          return {
+            content: [
+              {
+                type: 'text' as const,
+                text: JSON.stringify(
+                  {
+                    valid: false,
+                    error:
+                      'Invalid timestamp: timestamp is in the future. Possible clock skew or tampered request.',
+                  },
+                  null,
+                  2,
+                ),
+              },
+            ],
+          };
+        }
+
+        // Calcular HMAC-SHA256
+        // Algoritmo: HMAC(signing_secret, timestamp + "." + raw_body)
+        const signedPayload = `${timestamp}.${params.payload}`;
+        const expectedHmac = createHmac('sha256', params.webhook_secret)
+          .update(signedPayload, 'utf8')
+          .digest('hex');
+
+        // Comparação constant-time para prevenir timing attacks
+        let signaturesMatch = false;
+        try {
+          const expectedBuffer = Buffer.from(expectedHmac, 'hex');
+          const receivedBuffer = Buffer.from(receivedSignature, 'hex');
+
+          if (expectedBuffer.length === receivedBuffer.length) {
+            signaturesMatch = timingSafeEqual(expectedBuffer, receivedBuffer);
+          }
+        } catch {
+          // Buffer com hex inválido — assinatura malformada
+          signaturesMatch = false;
+        }
+
+        if (!signaturesMatch) {
+          return {
+            content: [
+              {
+                type: 'text' as const,
+                text: JSON.stringify(
+                  {
+                    valid: false,
+                    error:
+                      'Invalid signature: HMAC-SHA256 mismatch. The webhook payload may have been tampered with, or the wrong signing secret was used.',
+                  },
+                  null,
+                  2,
+                ),
+              },
+            ],
+          };
+        }
+
+        // Extrair tipo de evento do payload (sem logar o conteúdo completo)
+        let eventType: string | undefined;
+        try {
+          const parsed = JSON.parse(params.payload) as Record<string, unknown>;
+          if (typeof parsed['type'] === 'string') {
+            eventType = parsed['type'];
+          }
+        } catch {
+          // Payload não é JSON válido — ainda pode ser válido dependendo do uso
+        }
+
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify(
+                {
+                  valid: true,
+                  timestamp: timestampNumber,
+                  timestamp_age_seconds: ageSeconds,
+                  ...(eventType !== undefined ? { event_type: eventType } : {}),
+                  message:
+                    'Assinatura válida. O webhook é genuíno e foi enviado pela Certynix.',
+                },
+                null,
+                2,
+              ),
+            },
+          ],
+        };
+      } catch (err) {
+        // NUNCA incluir webhook_secret em mensagens de erro
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify(
+                {
+                  valid: false,
+                  error:
+                    err instanceof Error
+                      ? `Verification failed: ${err.message}`
+                      : 'Verification failed: unknown error',
+                },
+                null,
+                2,
+              ),
+            },
+          ],
+        };
+      }
+    },
+  );
+}

package/src/utils/format.ts

@@ -0,0 +1,20 @@
+import { sanitizeForOutput } from './mask.js';
+
+/**
+ * Formata um asset para exibição no output de uma tool call.
+ * Remove campos sensíveis antes de serializar.
+ */
+export function formatAssetOutput(asset: unknown): string {
+  return JSON.stringify(sanitizeForOutput(asset), null, 2);
+}
+
+/**
+ * Formata um erro para mensagem legível no output de uma tool call.
+ * Nunca inclui stack trace ou detalhes internos.
+ */
+export function formatError(err: unknown): string {
+  if (err instanceof Error) {
+    return `Error: ${err.message}`;
+  }
+  return `Unknown error: ${String(err)}`;
+}

package/src/utils/mask.ts

@@ -0,0 +1,41 @@
+/**
+ * Máscara de campos sensíveis para logs e outputs do MCP Server.
+ * NUNCA expor API Keys, secrets ou tokens em qualquer output.
+ */
+
+/**
+ * Mascara uma API Key para exibição em logs.
+ * Formato de saída: cnx_live_sk_*** (primeiros 12 caracteres + ***)
+ */
+export function maskApiKey(key: string): string {
+  if (!key.startsWith('cnx_')) return '***';
+  return key.substring(0, 12) + '***';
+}
+
+/**
+ * Remove campos sensíveis recursivamente de um objeto antes de qualquer output.
+ * Campos sensíveis nunca devem aparecer em respostas de tool calls.
+ */
+export function sanitizeForOutput(obj: unknown): unknown {
+  if (typeof obj !== 'object' || obj === null) return obj;
+  if (Array.isArray(obj)) return obj.map(sanitizeForOutput);
+
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(obj as Record<string, unknown>)) {
+    const sensitiveKeys = [
+      'apiKey',
+      'api_key',
+      'secret',
+      'token',
+      'password',
+      'signing_secret',
+      'webhook_secret',
+    ];
+    if (sensitiveKeys.some((k) => key.toLowerCase().includes(k.toLowerCase()))) {
+      result[key] = '***';
+    } else {
+      result[key] = sanitizeForOutput(value);
+    }
+  }
+  return result;
+}