@certynix/mcp 1.0.0

package/dist/tools/list-assets.js

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+import { formatError } from '../utils/format.js';
+export function registerListAssetsTool(server, client) {
+    server.tool('list_assets', 'Lista os ativos digitais registrados pela sua organização. Suporta filtros por status e período. Retorna até 100 assets por chamada com cursor para paginação.', {
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .optional()
+            .describe('Número de assets por página (máximo 100, padrão 20).'),
+        cursor: z
+            .string()
+            .optional()
+            .describe('Cursor de paginação retornado pela chamada anterior.'),
+        status: z
+            .enum(['pending', 'verified', 'failed'])
+            .optional()
+            .describe('Filtrar por status do asset.'),
+        created_after: z
+            .string()
+            .optional()
+            .describe('Retornar apenas assets criados após esta data (ISO 8601).'),
+        created_before: z
+            .string()
+            .optional()
+            .describe('Retornar apenas assets criados antes desta data (ISO 8601).'),
+    }, async (params) => {
+        try {
+            const page = await client.assets.listPage({
+                ...(params.limit !== undefined ? { limit: params.limit } : {}),
+                ...(params.cursor !== undefined ? { cursor: params.cursor } : {}),
+                ...(params.status !== undefined ? { status: params.status } : {}),
+                ...(params.created_after !== undefined ? { createdAfter: params.created_after } : {}),
+                ...(params.created_before !== undefined ? { createdBefore: params.created_before } : {}),
+            });
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            data: page.data.map((asset) => ({
+                                id: asset.id,
+                                hash: asset.hash,
+                                status: asset.status,
+                                trust_score: asset.trustScore,
+                                source_type: asset.sourceType,
+                                is_first_registrant: asset.isFirstRegistrant,
+                                created_at: asset.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', text: formatError(err) }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/list-audit-logs.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CertynixClient } from '@certynix/sdk';
+export declare function registerListAuditLogsTool(server: McpServer, client: CertynixClient): void;

package/dist/tools/list-audit-logs.js

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+import { formatError } from '../utils/format.js';
+export function registerListAuditLogsTool(server, client) {
+    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',
+                        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', text: formatError(err) }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/list-webhooks.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CertynixClient } from '@certynix/sdk';
+export declare function registerListWebhooksTool(server: McpServer, client: CertynixClient): void;

package/dist/tools/list-webhooks.js

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+import { formatError } from '../utils/format.js';
+export function registerListWebhooksTool(server, client) {
+    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',
+                        text: JSON.stringify({
+                            data: page.data.map((webhook) => ({
+                                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', text: formatError(err) }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/register-asset.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CertynixClient } from '@certynix/sdk';
+export declare function registerRegisterAssetTool(server: McpServer, client: CertynixClient): void;

package/dist/tools/register-asset.js

@@ -0,0 +1,87 @@
+import { z } from 'zod';
+import { formatError } from '../utils/format.js';
+export function registerRegisterAssetTool(server, client) {
+    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',
+                            text: 'Error: one of hash_sha256, url, or file_base64 is required',
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            let input;
+            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 } : {}),
+                };
+            }
+            else if (params.url) {
+                input = {
+                    url: params.url,
+                    ...(params.filename !== undefined ? { filename: params.filename } : {}),
+                };
+            }
+            else {
+                const buffer = Buffer.from(params.file_base64, 'base64');
+                input = {
+                    file: buffer,
+                    ...(params.filename !== undefined ? { filename: params.filename } : {}),
+                    ...(params.mime_type !== undefined ? { mime_type: params.mime_type } : {}),
+                };
+            }
+            const asset = await client.assets.register(input);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        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', text: formatError(err) }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/revoke-api-key.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CertynixClient } from '@certynix/sdk';
+export declare function registerRevokeApiKeyTool(server: McpServer, client: CertynixClient): void;

package/dist/tools/revoke-api-key.js

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+import { formatError } from '../utils/format.js';
+export function registerRevokeApiKeyTool(server, client) {
+    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',
+                            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',
+                        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', text: formatError(err) }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/verify-asset.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CertynixClient } from '@certynix/sdk';
+export declare function registerVerifyAssetTool(server: McpServer, client: CertynixClient): void;

package/dist/tools/verify-asset.js

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+import { formatError } from '../utils/format.js';
+export function registerVerifyAssetTool(server, client) {
+    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',
+                            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);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        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', text: formatError(err) }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/verify-webhook-signature.d.ts

@@ -0,0 +1,7 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Verifica assinatura de webhook localmente via HMAC-SHA256.
+ * NÃO realiza chamada à API — operação 100% local.
+ * NUNCA loga o webhook_secret.
+ */
+export declare function registerVerifyWebhookSignatureTool(server: McpServer): void;

package/dist/tools/verify-webhook-signature.js

@@ -0,0 +1,178 @@
+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) {
+    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;
+            let receivedSignature;
+            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',
+                            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',
+                            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',
+                            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',
+                            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',
+                            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;
+            try {
+                const parsed = JSON.parse(params.payload);
+                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',
+                        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',
+                        text: JSON.stringify({
+                            valid: false,
+                            error: err instanceof Error
+                                ? `Verification failed: ${err.message}`
+                                : 'Verification failed: unknown error',
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+    });
+}

package/dist/utils/format.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Formata um asset para exibição no output de uma tool call.
+ * Remove campos sensíveis antes de serializar.
+ */
+export declare function formatAssetOutput(asset: unknown): string;
+/**
+ * Formata um erro para mensagem legível no output de uma tool call.
+ * Nunca inclui stack trace ou detalhes internos.
+ */
+export declare function formatError(err: unknown): string;

package/dist/utils/format.js

@@ -0,0 +1,18 @@
+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) {
+    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) {
+    if (err instanceof Error) {
+        return `Error: ${err.message}`;
+    }
+    return `Unknown error: ${String(err)}`;
+}

package/dist/utils/mask.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 declare function maskApiKey(key: string): string;
+/**
+ * Remove campos sensíveis recursivamente de um objeto antes de qualquer output.
+ * Campos sensíveis nunca devem aparecer em respostas de tool calls.
+ */
+export declare function sanitizeForOutput(obj: unknown): unknown;

package/dist/utils/mask.js

@@ -0,0 +1,42 @@
+/**
+ * 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) {
+    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) {
+    if (typeof obj !== 'object' || obj === null)
+        return obj;
+    if (Array.isArray(obj))
+        return obj.map(sanitizeForOutput);
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        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;
+}