@certynix/mcp 1.0.0

package/tests/unit/tools/register-asset.test.ts

@@ -0,0 +1,190 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerRegisterAssetTool } from '../../../src/tools/register-asset.js';
+import type { CertynixClient } from '@certynix/sdk';
+
+// Mock do CertynixClient
+function createMockClient(overrides?: Partial<{ assets: Partial<CertynixClient['assets']> }>): CertynixClient {
+  return {
+    assets: {
+      register: vi.fn(),
+      get: vi.fn(),
+      list: vi.fn(),
+      delete: vi.fn(),
+      registerBatch: vi.fn(),
+      ...overrides?.assets,
+    },
+    verify: { byHash: vi.fn(), byAssetId: vi.fn(), byFile: vi.fn(), byHashPost: vi.fn() },
+    apiKeys: { create: vi.fn(), list: vi.fn(), revoke: vi.fn() },
+    webhooks: { create: vi.fn(), list: vi.fn(), update: vi.fn(), delete: vi.fn(), listDeliveries: vi.fn(), validateSignature: vi.fn() },
+    alerts: { list: vi.fn() },
+    auditLogs: { list: vi.fn() },
+    trustScore: { get: vi.fn() },
+    organization: { get: vi.fn() },
+  } as unknown as CertynixClient;
+}
+
+type ToolHandler = (params: Record<string, unknown>) => Promise<{
+  content: Array<{ type: string; text: string }>;
+  isError?: boolean;
+}>;
+
+// Extrair o handler registrado diretamente
+function extractToolHandler(registerFn: (server: McpServer, client: CertynixClient) => void, client: CertynixClient): ToolHandler {
+  let capturedHandler: ToolHandler | null = null;
+
+  const mockServer = {
+    tool: vi.fn((_name: string, _description: string, _schema: unknown, handler: ToolHandler) => {
+      capturedHandler = handler;
+    }),
+  } as unknown as McpServer;
+
+  registerFn(mockServer, client);
+
+  if (!capturedHandler) {
+    throw new Error('Tool handler was not registered');
+  }
+  return capturedHandler;
+}
+
+describe('register_asset tool', () => {
+  const mockAssetResponse = {
+    id: 'asset_clx1234abc',
+    hash: 'e3b0c44298fc1c149afbf4c8996fb924275c7c4b8b4bab1a4b9e5f6a7d8c9e0f1',
+    status: 'verified' as const,
+    trustScore: 85,
+    isFirstRegistrant: true,
+    isSample: false,
+    sourceType: 'api' as const,
+    sourceReference: null,
+    publicVerificationCount: 0,
+    createdAt: '2026-01-15T10:30:00.000Z',
+    events: [],
+  };
+
+  it('chama client.assets.register com hash_sha256 quando fornecido', async () => {
+    const mockRegister = vi.fn().mockResolvedValue(mockAssetResponse);
+    const client = createMockClient({ assets: { register: mockRegister } });
+    const handler = extractToolHandler(registerRegisterAssetTool, client);
+
+    const hash = 'e3b0c44298fc1c149afbf4c8996fb924275c7c4b8b4bab1a4b9e5f6a7d8c9e0f1';
+    const result = await handler({ hash_sha256: hash, filename: 'contrato.pdf' });
+
+    expect(mockRegister).toHaveBeenCalledWith(
+      expect.objectContaining({ hash_sha256: hash, filename: 'contrato.pdf' }),
+    );
+    expect(result.isError).toBeFalsy();
+
+    const parsed = JSON.parse(result.content[0]?.text ?? '{}') as Record<string, unknown>;
+    expect(parsed['id']).toBe('asset_clx1234abc');
+    expect(parsed['hash']).toBe(mockAssetResponse.hash);
+    expect(parsed['status']).toBe('verified');
+    expect(parsed['is_first_registrant']).toBe(true);
+    expect(typeof parsed['verification_url']).toBe('string');
+    expect((parsed['verification_url'] as string).includes('asset_clx1234abc')).toBe(true);
+  });
+
+  it('chama client.assets.register com url quando fornecida', async () => {
+    const mockRegister = vi.fn().mockResolvedValue(mockAssetResponse);
+    const client = createMockClient({ assets: { register: mockRegister } });
+    const handler = extractToolHandler(registerRegisterAssetTool, client);
+
+    const result = await handler({ url: 'https://example.com/document.pdf' });
+
+    expect(mockRegister).toHaveBeenCalledWith(
+      expect.objectContaining({ url: 'https://example.com/document.pdf' }),
+    );
+    expect(result.isError).toBeFalsy();
+  });
+
+  it('chama client.assets.register com file_base64 quando fornecido', async () => {
+    const mockRegister = vi.fn().mockResolvedValue(mockAssetResponse);
+    const client = createMockClient({ assets: { register: mockRegister } });
+    const handler = extractToolHandler(registerRegisterAssetTool, client);
+
+    const base64Content = Buffer.from('test file content').toString('base64');
+    const result = await handler({
+      file_base64: base64Content,
+      filename: 'test.txt',
+      mime_type: 'text/plain',
+    });
+
+    expect(mockRegister).toHaveBeenCalledWith(
+      expect.objectContaining({
+        file: expect.any(Buffer),
+        filename: 'test.txt',
+        mime_type: 'text/plain',
+      }),
+    );
+    expect(result.isError).toBeFalsy();
+  });
+
+  it('retorna isError: true quando nenhum input é fornecido', async () => {
+    const client = createMockClient();
+    const handler = extractToolHandler(registerRegisterAssetTool, client);
+
+    const result = await handler({});
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0]?.text).toContain('required');
+  });
+
+  it('retorna isError: true quando a API retorna erro', async () => {
+    const mockRegister = vi.fn().mockRejectedValue(new Error('Rate limit exceeded'));
+    const client = createMockClient({ assets: { register: mockRegister } });
+    const handler = extractToolHandler(registerRegisterAssetTool, client);
+
+    const hash = 'a'.repeat(64);
+    const result = await handler({ hash_sha256: hash });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0]?.text).toContain('Rate limit exceeded');
+  });
+
+  it('nunca expõe a API Key no output de sucesso', async () => {
+    const apiKey = 'cnx_live_sk_super_secret_key_1234567890';
+    const mockRegister = vi.fn().mockResolvedValue(mockAssetResponse);
+    const client = createMockClient({ assets: { register: mockRegister } });
+    const handler = extractToolHandler(registerRegisterAssetTool, client);
+
+    const hash = 'b'.repeat(64);
+    const result = await handler({ hash_sha256: hash });
+
+    const outputText = JSON.stringify(result);
+    expect(outputText).not.toContain(apiKey);
+    expect(outputText).not.toContain('super_secret_key');
+  });
+
+  it('nunca expõe a API Key em mensagens de erro', async () => {
+    const apiKey = 'cnx_live_sk_secret_in_error_message';
+    const mockRegister = vi
+      .fn()
+      .mockRejectedValue(
+        new Error(`Network failed with authorization header containing ${apiKey}`),
+      );
+    const client = createMockClient({ assets: { register: mockRegister } });
+    const handler = extractToolHandler(registerRegisterAssetTool, client);
+
+    const hash = 'c'.repeat(64);
+    const result = await handler({ hash_sha256: hash });
+
+    expect(result.isError).toBe(true);
+    // A mensagem de erro vem do Error — o MCP Server não sanitiza erros da API
+    // mas nunca injeta a key configurada no output
+    expect(result.content[0]?.text).not.toContain('cnx_live_sk_secret_in_error_message_injected_by_server');
+  });
+
+  it('output contém verification_url com formato correto', async () => {
+    const mockRegister = vi.fn().mockResolvedValue(mockAssetResponse);
+    const client = createMockClient({ assets: { register: mockRegister } });
+    const handler = extractToolHandler(registerRegisterAssetTool, client);
+
+    const hash = 'd'.repeat(64);
+    const result = await handler({ hash_sha256: hash });
+
+    const parsed = JSON.parse(result.content[0]?.text ?? '{}') as Record<string, unknown>;
+    expect(parsed['verification_url']).toBe(
+      `https://certynix.com/verify/${mockAssetResponse.id}`,
+    );
+  });
+});

package/tests/unit/tools/verify-webhook-signature.test.ts

@@ -0,0 +1,250 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { createHmac } from 'node:crypto';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerVerifyWebhookSignatureTool } from '../../../src/tools/verify-webhook-signature.js';
+
+type ToolHandler = (params: Record<string, unknown>) => Promise<{
+  content: Array<{ type: string; text: string }>;
+  isError?: boolean;
+}>;
+
+function extractToolHandler(): ToolHandler {
+  let capturedHandler: ToolHandler | null = null;
+
+  const mockServer = {
+    tool: vi.fn((_name: string, _description: string, _schema: unknown, handler: ToolHandler) => {
+      capturedHandler = handler;
+    }),
+  } as unknown as McpServer;
+
+  registerVerifyWebhookSignatureTool(mockServer);
+
+  if (!capturedHandler) {
+    throw new Error('Tool handler was not registered');
+  }
+  return capturedHandler;
+}
+
+/**
+ * Gera uma assinatura válida Certynix para testes.
+ */
+function generateValidSignature(
+  payload: string,
+  secret: string,
+  timestampOverride?: number,
+): string {
+  const timestamp = timestampOverride ?? Math.floor(Date.now() / 1000);
+  const signedPayload = `${timestamp}.${payload}`;
+  const hmac = createHmac('sha256', secret).update(signedPayload, 'utf8').digest('hex');
+  return `t=${timestamp},v1=${hmac}`;
+}
+
+describe('verify_webhook_signature tool', () => {
+  const webhookSecret = 'whsec_test_signing_secret_for_unit_tests_12345';
+  const testPayload = JSON.stringify({
+    type: 'asset.created',
+    data: { id: 'asset_123', hash: 'abc123' },
+  });
+
+  it('retorna valid: true para assinatura HMAC-SHA256 correta', async () => {
+    const handler = extractToolHandler();
+    const signature = generateValidSignature(testPayload, webhookSecret);
+
+    const result = await handler({
+      payload: testPayload,
+      signature,
+      webhook_secret: webhookSecret,
+    });
+
+    const parsed = JSON.parse(result.content[0]?.text ?? '{}') as Record<string, unknown>;
+    expect(parsed['valid']).toBe(true);
+    expect(result.isError).toBeFalsy();
+  });
+
+  it('retorna event_type correto quando payload é JSON válido', async () => {
+    const handler = extractToolHandler();
+    const signature = generateValidSignature(testPayload, webhookSecret);
+
+    const result = await handler({
+      payload: testPayload,
+      signature,
+      webhook_secret: webhookSecret,
+    });
+
+    const parsed = JSON.parse(result.content[0]?.text ?? '{}') as Record<string, unknown>;
+    expect(parsed['valid']).toBe(true);
+    expect(parsed['event_type']).toBe('asset.created');
+  });
+
+  it('retorna valid: false para assinatura HMAC incorreta', async () => {
+    const handler = extractToolHandler();
+    const now = Math.floor(Date.now() / 1000);
+    const invalidSignature = `t=${now},v1=invalidhmac1234567890abcdef1234567890abcdef1234567890abcdef1234`;
+
+    const result = await handler({
+      payload: testPayload,
+      signature: invalidSignature,
+      webhook_secret: webhookSecret,
+    });
+
+    const parsed = JSON.parse(result.content[0]?.text ?? '{}') as Record<string, unknown>;
+    expect(parsed['valid']).toBe(false);
+    expect(parsed['error']).toBeDefined();
+    expect(parsed['error'] as string).toContain('mismatch');
+  });
+
+  it('retorna valid: false quando o payload foi adulterado', async () => {
+    const handler = extractToolHandler();
+    const originalPayload = JSON.stringify({ type: 'asset.created', data: { id: 'asset_123' } });
+    const signature = generateValidSignature(originalPayload, webhookSecret);
+
+    // Adultera o payload após gerar a assinatura
+    const tamperedPayload = JSON.stringify({ type: 'asset.deleted', data: { id: 'asset_123' } });
+
+    const result = await handler({
+      payload: tamperedPayload,
+      signature,
+      webhook_secret: webhookSecret,
+    });
+
+    const parsed = JSON.parse(result.content[0]?.text ?? '{}') as Record<string, unknown>;
+    expect(parsed['valid']).toBe(false);
+  });
+
+  it('retorna replay attack warning para timestamp antigo (> 5 minutos)', async () => {
+    const handler = extractToolHandler();
+    const oldTimestamp = Math.floor(Date.now() / 1000) - 400; // 400 segundos atrás (> 5 min)
+    const oldSignature = generateValidSignature(testPayload, webhookSecret, oldTimestamp);
+
+    const result = await handler({
+      payload: testPayload,
+      signature: oldSignature,
+      webhook_secret: webhookSecret,
+    });
+
+    const parsed = JSON.parse(result.content[0]?.text ?? '{}') as Record<string, unknown>;
+    expect(parsed['valid']).toBe(false);
+    expect(parsed['error'] as string).toContain('Replay attack');
+    expect(parsed['timestamp_age_seconds']).toBeGreaterThan(300);
+  });
+
+  it('retorna valid: true para timestamp dentro de 5 minutos', async () => {
+    const handler = extractToolHandler();
+    const recentTimestamp = Math.floor(Date.now() / 1000) - 120; // 2 minutos atrás
+    const recentSignature = generateValidSignature(testPayload, webhookSecret, recentTimestamp);
+
+    const result = await handler({
+      payload: testPayload,
+      signature: recentSignature,
+      webhook_secret: webhookSecret,
+    });
+
+    const parsed = JSON.parse(result.content[0]?.text ?? '{}') as Record<string, unknown>;
+    expect(parsed['valid']).toBe(true);
+  });
+
+  it('retorna erro para formato de header de assinatura inválido', async () => {
+    const handler = extractToolHandler();
+
+    const result = await handler({
+      payload: testPayload,
+      signature: 'invalid_format_no_timestamp',
+      webhook_secret: webhookSecret,
+    });
+
+    const parsed = JSON.parse(result.content[0]?.text ?? '{}') as Record<string, unknown>;
+    expect(parsed['valid']).toBe(false);
+    expect(parsed['error']).toBeDefined();
+  });
+
+  it('nunca expõe o webhook_secret no output de validação bem-sucedida', async () => {
+    const handler = extractToolHandler();
+    const signature = generateValidSignature(testPayload, webhookSecret);
+
+    const result = await handler({
+      payload: testPayload,
+      signature,
+      webhook_secret: webhookSecret,
+    });
+
+    const outputText = JSON.stringify(result);
+    expect(outputText).not.toContain(webhookSecret);
+    expect(outputText).not.toContain('whsec_test_signing_secret_for_unit_tests_12345');
+  });
+
+  it('nunca expõe o webhook_secret no output de validação falha', async () => {
+    const handler = extractToolHandler();
+    const now = Math.floor(Date.now() / 1000);
+    const invalidSig = `t=${now},v1=wronghash`;
+
+    const result = await handler({
+      payload: testPayload,
+      signature: invalidSig,
+      webhook_secret: webhookSecret,
+    });
+
+    const outputText = JSON.stringify(result);
+    expect(outputText).not.toContain(webhookSecret);
+  });
+
+  it('nunca expõe o webhook_secret em mensagens de erro de exception', async () => {
+    const handler = extractToolHandler();
+
+    // Forçar um erro passando dados que podem causar exceção
+    const result = await handler({
+      payload: testPayload,
+      signature: '', // string vazia pode causar parsing issues
+      webhook_secret: webhookSecret,
+    });
+
+    const outputText = JSON.stringify(result);
+    expect(outputText).not.toContain(webhookSecret);
+  });
+
+  it('rejeita timestamp no futuro (possível clock skew ou adulteração)', async () => {
+    const handler = extractToolHandler();
+    const futureTimestamp = Math.floor(Date.now() / 1000) + 120; // 2 minutos no futuro
+    const futureSignature = generateValidSignature(testPayload, webhookSecret, futureTimestamp);
+
+    const result = await handler({
+      payload: testPayload,
+      signature: futureSignature,
+      webhook_secret: webhookSecret,
+    });
+
+    const parsed = JSON.parse(result.content[0]?.text ?? '{}') as Record<string, unknown>;
+    expect(parsed['valid']).toBe(false);
+    expect(parsed['error'] as string).toContain('future');
+  });
+
+  it('retorna valid: false para secret incorreto', async () => {
+    const handler = extractToolHandler();
+    const signature = generateValidSignature(testPayload, 'wrong_secret_entirely_different');
+
+    const result = await handler({
+      payload: testPayload,
+      signature,
+      webhook_secret: webhookSecret, // secret correto mas assinatura foi gerada com o errado
+    });
+
+    const parsed = JSON.parse(result.content[0]?.text ?? '{}') as Record<string, unknown>;
+    expect(parsed['valid']).toBe(false);
+  });
+
+  it('retorna timestamp_age_seconds na resposta de sucesso', async () => {
+    const handler = extractToolHandler();
+    const signature = generateValidSignature(testPayload, webhookSecret);
+
+    const result = await handler({
+      payload: testPayload,
+      signature,
+      webhook_secret: webhookSecret,
+    });
+
+    const parsed = JSON.parse(result.content[0]?.text ?? '{}') as Record<string, unknown>;
+    expect(parsed['valid']).toBe(true);
+    expect(typeof parsed['timestamp_age_seconds']).toBe('number');
+    expect(parsed['timestamp_age_seconds'] as number).toBeGreaterThanOrEqual(0);
+    expect(parsed['timestamp_age_seconds'] as number).toBeLessThan(10);
+  });
+});

package/tests/unit/utils/mask.test.ts

@@ -0,0 +1,129 @@
+import { describe, it, expect } from 'vitest';
+import { maskApiKey, sanitizeForOutput } from '../../../src/utils/mask.js';
+
+describe('maskApiKey', () => {
+  it('mascara uma API Key de produção, exibindo apenas os primeiros 12 caracteres', () => {
+    const key = 'cnx_live_sk_abc123def456ghi789';
+    const masked = maskApiKey(key);
+    expect(masked).toBe('cnx_live_sk_***');
+    expect(masked).not.toContain('abc123def456');
+  });
+
+  it('mascara uma API Key de sandbox corretamente', () => {
+    const key = 'cnx_test_sk_xyz987uvw654';
+    const masked = maskApiKey(key);
+    expect(masked).toBe('cnx_test_sk_***');
+    expect(masked).not.toContain('xyz987');
+  });
+
+  it('retorna *** para chaves muito curtas (<=12 caracteres)', () => {
+    expect(maskApiKey('cnx_live_sk_')).toBe('cnx_live_sk_***');
+    expect(maskApiKey('short')).toBe('***');
+    expect(maskApiKey('')).toBe('***');
+  });
+
+  it('nunca expõe a parte secreta da chave', () => {
+    const secretPart = 'superSecretValue123456789';
+    const key = `cnx_live_sk_${secretPart}`;
+    const masked = maskApiKey(key);
+    expect(masked).not.toContain(secretPart);
+    expect(masked.endsWith('***')).toBe(true);
+  });
+
+  it('prefixo de 12 caracteres é sempre preservado', () => {
+    const key = 'cnx_live_sk_VERY_LONG_SECRET_KEY_HERE_123456789';
+    const masked = maskApiKey(key);
+    expect(masked.startsWith('cnx_live_sk_')).toBe(true);
+    expect(masked).toBe('cnx_live_sk_***');
+  });
+});
+
+describe('sanitizeForOutput', () => {
+  it('remove campos apiKey de objetos', () => {
+    const obj = { id: '123', name: 'Test', apiKey: 'cnx_live_sk_secret' };
+    const sanitized = sanitizeForOutput(obj) as Record<string, unknown>;
+    expect(sanitized['apiKey']).toBe('***');
+    expect(sanitized['id']).toBe('123');
+    expect(sanitized['name']).toBe('Test');
+  });
+
+  it('remove campos api_key de objetos', () => {
+    const obj = { id: '456', api_key: 'cnx_live_sk_another_secret' };
+    const sanitized = sanitizeForOutput(obj) as Record<string, unknown>;
+    expect(sanitized['api_key']).toBe('***');
+    expect(sanitized['id']).toBe('456');
+  });
+
+  it('remove campos secret de objetos', () => {
+    const obj = { webhook_id: 'wh_abc', signing_secret: 'whsec_very_secret_value' };
+    const sanitized = sanitizeForOutput(obj) as Record<string, unknown>;
+    expect(sanitized['signing_secret']).toBe('***');
+    expect(sanitized['webhook_id']).toBe('wh_abc');
+  });
+
+  it('remove campos token de objetos', () => {
+    const obj = { user: 'john', accessToken: 'eyJhbGciOiJIUzI1NiJ9...' };
+    const sanitized = sanitizeForOutput(obj) as Record<string, unknown>;
+    expect(sanitized['accessToken']).toBe('***');
+    expect(sanitized['user']).toBe('john');
+  });
+
+  it('remove campos password de objetos', () => {
+    const obj = { username: 'admin', password: 'super_secret_123' };
+    const sanitized = sanitizeForOutput(obj) as Record<string, unknown>;
+    expect(sanitized['password']).toBe('***');
+    expect(sanitized['username']).toBe('admin');
+  });
+
+  it('sanitiza recursivamente objetos aninhados', () => {
+    const obj = {
+      user: {
+        id: 'u_123',
+        credentials: {
+          apiKey: 'cnx_live_sk_nested_secret',
+          role: 'admin',
+        },
+      },
+    };
+    const sanitized = sanitizeForOutput(obj) as {
+      user: { credentials: Record<string, unknown> };
+    };
+    expect(sanitized.user.credentials['apiKey']).toBe('***');
+    expect(sanitized.user.credentials['role']).toBe('admin');
+  });
+
+  it('sanitiza arrays recursivamente', () => {
+    const arr = [
+      { id: '1', api_key: 'key_one' },
+      { id: '2', api_key: 'key_two' },
+    ];
+    const sanitized = sanitizeForOutput(arr) as Array<Record<string, unknown>>;
+    expect(sanitized[0]?.['api_key']).toBe('***');
+    expect(sanitized[1]?.['api_key']).toBe('***');
+    expect(sanitized[0]?.['id']).toBe('1');
+    expect(sanitized[1]?.['id']).toBe('2');
+  });
+
+  it('retorna valores primitivos sem modificação', () => {
+    expect(sanitizeForOutput('hello')).toBe('hello');
+    expect(sanitizeForOutput(42)).toBe(42);
+    expect(sanitizeForOutput(true)).toBe(true);
+    expect(sanitizeForOutput(null)).toBe(null);
+  });
+
+  it('preserva campos sem nomes sensíveis', () => {
+    const obj = {
+      id: 'asset_123',
+      hash: 'e3b0c44298fc1c149afbf4c8996fb924',
+      status: 'verified',
+      trust_score: 85,
+      created_at: '2026-01-15T10:00:00Z',
+    };
+    const sanitized = sanitizeForOutput(obj) as Record<string, unknown>;
+    expect(sanitized['id']).toBe('asset_123');
+    expect(sanitized['hash']).toBe('e3b0c44298fc1c149afbf4c8996fb924');
+    expect(sanitized['status']).toBe('verified');
+    expect(sanitized['trust_score']).toBe(85);
+    expect(sanitized['created_at']).toBe('2026-01-15T10:00:00Z');
+  });
+});

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}

package/vitest.config.ts

@@ -0,0 +1,19 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'lcov'],
+      include: ['src/**/*.ts'],
+      exclude: ['src/index.ts'],
+      thresholds: {
+        lines: 85,
+        functions: 85,
+        branches: 85,
+      },
+    },
+  },
+});