feat: add structured data and API interaction tools

[avoidwork]

Description

Add six new tools for structured data and API interaction: REST API client, GraphQL client, webhook management, JSON manipulation, YAML manipulation, and cross-format data transformation.

Type of Change

• New feature (non-breaking change which adds functionality)
• Documentation update

Testing

• Unit tests added for all 6 tools in tests/unit/ (api.test.js, graphql.test.js, json.test.js, yaml.test.js, data.test.js, webhook.test.js)
• Integration tests added for api.test.js and webhook.test.js in tests/integration/
• URL allowlist validation tests (blocked schemes: file://, gopher://, dict://)
• Internal IP blocking tests (127.0.0.1, 0.0.0.0, 169.254.169.254)
• Authentication tests (Bearer, Basic, API Key)
• GraphQL depth/complexity limit tests
• Webhook HMAC-SHA256 signature verification tests
• JSON/YAML parse/transform/filter/serialize tests
• Data transformation tests (JSON ↔ YAML ↔ CSV)

Coverage

• Line coverage maintained

Checklist

• npm run lint passes
• Tests pass with maintained line coverage
• No forbidden patterns used
• Conventional Commit style applied

Files Changed (43 files, +4037 lines)

New Tools (src/tools/)

• api.js — REST API client with auth (Bearer, Basic, API Key), URL allowlist, timeout, response sanitization
• graphql.js — GraphQL client with query/mutation/introspection, depth/complexity limits
• json.js — JSON manipulation with parse/transform/filter/serialize, JSONPath access
• yaml.js — YAML manipulation with parse/transform/filter/serialize, path-based access
• webhook.js — Webhook management with create/list/delete, HMAC-SHA256 verification, rate limiting
• data.js — Cross-format data transformation (JSON ↔ YAML ↔ CSV) with mapping rules

Registration

• index.js — Tool registration with permissions and sub-agent mapping

Tests

• tests/unit/api.test.js — URL validation, auth, method tests
• tests/unit/graphql.test.js — Query/mutation/introspection tests
• tests/unit/json.test.js — Parse/transform/filter/serialize tests
• tests/unit/yaml.test.js — Parse/transform/filter/serialize tests
• tests/unit/data.test.js — Format conversion tests
• tests/unit/webhook.test.js — HMAC verification, CRUD tests
• tests/integration/api.test.js — Integration tests
• tests/integration/webhook.test.js — Integration tests
• tests/unit/tool_index.test.js — Updated for new tools

Dependencies

• package.json — Added node-fetch, graphql-request, jsonpath-plus, js-yaml, csv-parse, csv-generate
• package-lock.json — Updated

Security

• src/sandbox/urlFilter.js — Enhanced URL validation with internal IP blocking

OpenSpec

• openspec/changes/structured-data-api-tools/ — Proposal, design, tasks, specs
• openspec/specs/ — Delta specs for api, json, yaml, webhook, data-transform

Closes #788

[avoidwork]

Audit Results — Issue #788

Goal Fulfillment (7/7 complete)

Goal 1: REST API Client Tool ✅

• src/tools/api.js (239 lines) implements authenticated HTTP requests with Bearer, Basic, and API Key auth
• URL allowlist validation via src/sandbox/urlFilter.js
• Internal IP blocking (127.0.0.1, 0.0.0.0, 169.254.169.254)
• Timeout enforcement via AbortController (default 30s)
• Response header sanitization (strips Set-Cookie, WWW-Authenticate)
• Response body size limit (default 10MB)
• Structured error objects with HTTP status, response body, and error message

Goal 2: GraphQL Client Tool ✅

• src/tools/graphql.js (346 lines) implements query, mutation, and introspection support
• Query depth limiting (default: 10) and complexity limiting (default: 1000)
• Variables properly serialized
• Schema introspection when enabled
• URL allowlist validation (same as REST client)
• Structured GraphQL error handling

Goal 3: Webhook Management Tool ✅

• src/tools/webhook.js (228 lines) implements create, list, delete, and verify actions
• HMAC-SHA256 signature verification using crypto.timingSafeEqual
• Signature expiration check (5 minute window)
• Missing signature rejection (401 status)
• Rate limiting per source IP (default: 100 req/min)
• Webhook secret storage in process.env only

Goal 4: JSON Manipulation Tool ✅

• src/tools/json.js (272 lines) implements parse, transform, filter, serialize actions
• JSONPath-based path access via jsonpath-plus
• Error handling for invalid JSON
• Support for nested path access and array indexing
• Descriptive error messages

Goal 5: YAML Manipulation Tool ✅

• src/tools/yaml.js (287 lines) implements parse, transform, filter, serialize actions
• YAML parsing and serialization via js-yaml
• Path-based access for nested YAML structures
• YAML anchor and reference handling
• Multi-document YAML support

Goal 6: Data Transformation Tool ✅

• src/tools/data.js (273 lines) implements cross-format conversion (JSON ↔ YAML ↔ CSV)
• Mapping rules for field transformation
• CSV parsing/generation via csv-parse and csv-generate
• Encoding support (UTF-8)
• Error handling for unsupported formats

Goal 7: Integration with Existing Patterns ✅

• All 6 tools follow the established pattern: zod schema → impl function → registration
• Registered in src/tools/index.js with appropriate permissions
• Permissions: network:outbound for api/graphql/webhook, filesystem:read for json/yaml/data
• Sub-agent mapping configured for search, research, coding, documentation, debug agents
• Consistent error handling across all tools

Spec Compliance

All 5 spec files (api, json, yaml, webhook, data-transform) are satisfied by the implementation. Each requirement has corresponding test coverage.

Task Completion

75/75 tasks complete. All tasks in tasks.md marked [x].

Quality Check

• No obvious issues or missing edge cases
• All security considerations addressed (URL allowlist, credential storage, response sanitization, HMAC verification)
• All dependencies added to package.json (node-fetch, graphql-request, jsonpath-plus, js-yaml, csv-parse, csv-generate)
• Tests mirror src/ structure in tests/unit/
• Integration tests added for api and webhook tools

Summary

All 7 goals fulfilled. Implementation is complete, well-structured, and follows project conventions. 43 files changed, +4037 lines, -14 lines.