API Security Contract

June 2, 2026 ยท View on GitHub

HeyClaude exposes a public read-only registry API plus a small set of limited dynamic endpoints. Registry publishing is not exposed over the public API.

Public Read-Only Surfaces

  • /api/registry/manifest
  • /api/registry/categories
  • /api/registry/search
  • /api/registry/feed
  • /api/registry/diff
  • /api/registry/entries/{category}/{slug}
  • /api/registry/entries/{category}/{slug}/llms
  • /api/mcp
  • /data/*.json registry artifacts
  • /data/feeds/index.json
  • /data/feeds/categories/{category}.json
  • /data/feeds/platforms/{platform}.json
  • /data/skill-adapters/... generated adapters
  • /feed.xml and static registry changelog artifacts

Limited Dynamic Surfaces

  • /api/votes/query
  • /api/votes/toggle
  • /api/community-signals
  • /api/community-signals/query
  • /api/intent-events
  • /api/newsletter/subscribe
  • /api/newsletter/webhook
  • /api/og
  • /api/submissions/preflight
  • /api/listing-leads
  • /api/admin/listing-leads
  • /api/admin/jobs
  • /api/admin/jobs/health

Controls

  • API route contracts live in apps/web/src/lib/api/contracts.ts. Route files under apps/web/src/routes/api/** are thin TanStack server handlers that delegate to the central router in apps/web/src/lib/api/router.ts.
  • Request params, queries, and JSON bodies are validated with Zod. The generated OpenAPI document in cloudflare/api-schema-heyclaude-openapi.yaml is derived from those Zod contracts with pnpm generate:openapi and checked with pnpm validate:openapi.
  • API errors use one normalized envelope: { ok: false, error: { code, message, details? }, requestId? }.
  • Public browser-facing endpoints keep origin checks and route-level rate limits.
  • JSON writes require content-type validation and payload size limits.
  • Admin review endpoints require bearer or admin-token headers.
  • Webhooks require provider signatures when configured.
  • Newsletter template syncing is a local operator script that talks to Resend Templates only; the public site does not expose campaign-send, scheduling, or template-management endpoints.
  • Website submission preflight requires origin checks, payload limits, schema validation, honeypot discard logging, and existing-content duplicate checks. It never creates GitHub issues, branches, pull requests, labels, comments, or registry content.
  • Website submissions do not accept or publish package uploads. Community ZIP/MCPB artifacts are review/quarantine material only; public downloads are maintainer-built artifacts after review.
  • PR creation and final review happen in the private Cloudflare submission gate through GitHub App user auth, webhooks, Queues, Durable Objects, and D1/R2.
  • Cloudflare rate-limit bindings are configured for registry, dynamic, strict, and MCP routes. The public no-key MCP endpoint uses a dedicated API_MCP_RATE_LIMIT binding with a 60 requests/minute/IP production cap. In-process limits remain a local/dev fallback when the Worker binding is unavailable.
  • Worker responses attach security headers in code as well as static asset headers: CSP, HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, and Cross-Origin-Opener-Policy.
  • No public website endpoint may import content into the registry or publish submissions directly. Content PR creation and direct merge decisions are isolated in the private submission gate after public checks and private maintainer review pass.
  • Job lead intake is intentionally shallow. Paid job publication remains gated by the token-protected D1 admin flow, which requires enriched reviewed listing content before active paid rows can publish.

Registry Trust Fields

Registry feeds and entry detail payloads may include trustSignals derived from existing file-backed facts:

  • package verification flags, first-party/external trust, and package SHA256
  • source URLs already present on the entry
  • content/repository/verification timestamps already present on the entry
  • generated adapter status and platform compatibility

These fields are factual metadata, not paid ranking or live health claims. Live link health checks can be added later as a separate generated artifact once they are backed by a real checker.