feat: add structured data and API interaction tools

[avoidwork]

Summary

Add a generic REST API client, GraphQL support, webhook management, and JSON/YAML manipulation tools.

Motivation

The existing tools handle web search and content extraction, but there is no structured API interaction capability. Office and marketing workflows frequently need to: call REST APIs (CRM, analytics, project management), query GraphQL endpoints, manage webhooks, and manipulate JSON/YAML data. Currently the agent must fall back to shell commands (curl, jq, yq) or rely on ad-hoc LLM reasoning, which is inconsistent and error-prone.

Proposed Solution

Create structured data and API tools:

• REST API Client: Make authenticated GET/POST/PUT/DELETE requests with configurable headers, body, and authentication (Bearer, Basic, API Key)
• GraphQL Client: Execute GraphQL queries and mutations with schema introspection
• Webhook Management: Create, list, and manage webhook endpoints with payload validation
• JSON Manipulation: Parse, transform, filter, and serialize JSON data with path-based access
• YAML Manipulation: Parse, transform, filter, and serialize YAML data with path-based access
• Data Transformation: Convert between JSON, YAML, CSV, and other formats with mapping rules

Each tool should follow the existing tool pattern in src/tools/ — a zod schema, an impl function, and registration in index.js with appropriate permissions (network:outbound for API calls, filesystem:read/write for data files).

Alternatives Considered

• Shell-based tools (curl, jq, yq): fragile, no structured output, requires user-installed dependencies.
• Rely on webExtract: only handles GET requests, no authentication or mutation capability.

OpenSpec Note

This project uses OpenSpec for feature development. If this request is approved, I will:

1. Run /opsx:propose to generate a full proposal with specs and tasks
2. Iterate on the design before any code is written
3. Follow the task-driven implementation workflow

Additional Context

This should integrate with the Google Workspace / Microsoft 365 gap (#783) — e.g., the REST API client could be used for API integrations that do not have dedicated tools yet. The existing webExtract tool handles GET requests; these tools would add full CRUD capability with authentication.

Dependencies

• REST API client: node-fetch (v3.x, native fetch API) or axios (v1.x). node-fetch preferred for zero-dependency, modern API.
• GraphQL client: graphql-request (v6.x) — lightweight, supports queries, mutations, schema introspection. Alternative: @apollo/client (heavier, React-focused, not suitable here).
• JSON manipulation: Built-in JSON.parse/stringify. For path-based access: jsonpath-plus (v8.x) — supports JSONPath expressions.
• YAML manipulation: js-yaml (v4.x) — well-maintained, supports load/dump with schema validation.
• Webhook management: Built-in HTTP server via Node's http module or fastify (v5.x) for a lightweight embedded server. fastify preferred for route management and plugin ecosystem.
• Data transformation: csv-parse and csv-generate (v6.x) from the same author as csv-stringify — reliable CSV handling.

Testing Strategy

• Unit tests: Mock HTTP responses for REST and GraphQL operations. Verify Zod schema validation for all inputs. Test JSON/YAML parsing, transformation, and serialization with known-good fixtures.
• Integration test: Spin up a local test server (fastify or express) with mock endpoints. Test REST CRUD, GraphQL queries/mutations, webhook registration, and payload validation.
• Webhook validation: Test HMAC signature verification against known secret and payload.
• Edge cases: Invalid JSON/YAML, malformed GraphQL queries, missing required headers, HTTP timeouts, webhook delivery failures, large payloads.

Security Considerations

• URL allowlist: All outbound URL operations must validate against an allowlist per AGENTS.md 1.2. Disallow file://, gopher://, dict:// schemes.
• Credential storage: API keys, bearer tokens, and webhook secrets stored in process.env only — never in config files, logs, or response bodies.
• Request validation: Validate all request URLs against the allowlist before making outbound requests. Reject requests to internal IPs (127.0.0.1, 0.0.0.0, 169.254.169.254) unless explicitly allowed.
• Webhook security: Verify incoming webhook signatures using HMAC-SHA256. Reject requests without valid signatures. Rate-limit webhook endpoints (default: 100 requests/minute per source IP).
• Response sanitization: Strip sensitive headers (Set-Cookie, WWW-Authenticate) from proxied responses. Limit response body size (default: 10MB) to prevent memory exhaustion.
• GraphQL: Limit query depth (default: 10) and complexity (default: 1000) to prevent DoS via deeply nested queries. Disable introspection in production unless explicitly enabled.
• Rate limiting: Implement client-side rate limiting (default: 10 requests/second) to avoid triggering provider blocks.

Implementation Notes

• Split into two tools: api (REST + GraphQL) and data (JSON/YAML manipulation, data transformation). Webhook management can be part of api or a separate webhook tool.
• REST API tool: Zod schema: { url: z.string().url(), method?: "GET" | "POST" | "PUT" | "DELETE" | "PATCH", headers?: Record<string, string>, body?: unknown, auth?: { type: "bearer" | "basic" | "apikey", token?: string, key?: string }, timeout?: number }.
• GraphQL tool: Zod schema: { url: z.string().url(), query: z.string(), variables?: Record<string, unknown>, operationName?: string, timeout?: number }.
• Data tool: Zod schema: { action: "parse" | "transform" | "filter" | "serialize", input: string, format: "json" | "yaml" | "csv", path?: string, mapping?: Record<string, string> }.
• Webhook tool: Zod schema: { action: "create" | "list" | "delete" | "verify", url?: string, secret?: string, events?: string[], payload?: unknown }.
• Timeouts: All HTTP operations should have configurable timeouts (default: 30s).
• Caching: Consider adding response caching for GET requests with TTL (configurable, default: 5 minutes).
• Error handling: Return structured error objects with HTTP status, response body, and error message. Never expose raw stack traces to the agent.