Skip to content

CATALOG-API.md

Latest commit

 

History

History
231 lines (173 loc) · 7.6 KB

CATALOG-API.md

File metadata and controls

231 lines (173 loc) · 7.6 KB

🌐 Catalog API Surface

Read-only HTTP API for skill discovery, search, comparison, install planning, and artifact downloads across the same catalog used by the public skill repository and curated derivative surfaces.

📊 Status

Feature State
✅ Catalog endpoints Implemented
✅ Auth (bearer + API key) Implemented
✅ Admin runtime auth Implemented
✅ Rate limiting Implemented
✅ Audit logging Implemented
✅ CORS and IP allowlists Implemented
✅ Maintenance mode Implemented
✅ Archive downloads Implemented
✅ OpenAPI spec Implemented — interactive Swagger UI served at /docs via openapi.yaml
⚠️ Governance backend Env-driven, in-process baseline; external gateway or IdP still optional

🎯 Purpose

The API provides a registry-style surface for:

  • 📋 Listing and filtering skills by quality, security, category, risk, and more
  • 📌 Fetching individual skill manifests
  • 🔎 Full-text search and multi-skill comparison
  • 📦 Bundle listing with availability
  • 📐 Read-only install plan generation
  • 📥 Downloading generated artifacts, archives, and checksum manifests

This same catalog and manifest surface is also the basis for:

  • local CLI install planning
  • MCP read-only discovery responses
  • A2A discovery and install-plan handoff
  • potential private catalogs with external auth layered on top

🚀 Quick Start

📦 From repo:

npm run api

📦 From published package:

npx awesome-omni-skills api --port 3333

⚙️ Custom host and port:

HOST=0.0.0.0 PORT=3333 npm run api

Defaults: 127.0.0.1:3333

🔐 Security Controls

All security controls are env-driven and optional:

Control Variable Example
🔑 Bearer auth OMNI_SKILLS_HTTP_BEARER_TOKEN replace-me
🗝️ API key auth OMNI_SKILLS_HTTP_API_KEYS key-a,key-b
🛂 Admin auth OMNI_SKILLS_HTTP_ADMIN_TOKEN admin-secret
🚦 Rate limiting OMNI_SKILLS_RATE_LIMIT_MAX + _WINDOW_MS 60 / 60000
📝 Audit logging OMNI_SKILLS_HTTP_AUDIT_LOG 1
🗂️ Audit format OMNI_SKILLS_HTTP_AUDIT_FORMAT json or text
📄 Audit file OMNI_SKILLS_HTTP_AUDIT_LOG_PATH /var/log/awesome-omni-skills/audit.log
🌍 CORS allowlist OMNI_SKILLS_HTTP_ALLOWED_ORIGINS https://app.example.com,https://*.example.org
🧱 IP allowlist OMNI_SKILLS_HTTP_ALLOWED_IPS 127.0.0.1/32,10.0.0.0/8
🔁 Trusted proxy OMNI_SKILLS_HTTP_TRUST_PROXY loopback
🚧 Maintenance mode OMNI_SKILLS_HTTP_MAINTENANCE_MODE 1
⏱️ Retry after OMNI_SKILLS_HTTP_MAINTENANCE_RETRY_AFTER_SECONDS 300

Behavior:

  • 🟢 /healthz remains always unauthenticated
  • 🔒 All other routes require auth when auth is enabled
  • 🛂 /admin/runtime requires the admin token when enabled
  • 🚦 Rate limiting is in-process with X-RateLimit-* response headers
  • 🧾 Every response carries X-Request-Id
  • 🚧 Maintenance mode returns 503 for non-health, non-admin routes

✅ Current governance decision

The current project direction is to reuse the same catalog format for public or private deployments and layer auth externally when needed.

That means:

  • the manifest and API shape stay shared
  • self-hosted and local deployments can stay on the in-process baseline
  • more advanced hosted governance can move to an external gateway or enterprise auth layer later without forking the data model

🔐 Full hardened example:

OMNI_SKILLS_HTTP_BEARER_TOKEN=replace-me \
OMNI_SKILLS_HTTP_API_KEYS=key-a,key-b \
OMNI_SKILLS_HTTP_ADMIN_TOKEN=admin-secret \
OMNI_SKILLS_RATE_LIMIT_MAX=60 \
OMNI_SKILLS_RATE_LIMIT_WINDOW_MS=60000 \
OMNI_SKILLS_HTTP_AUDIT_LOG=1 \
OMNI_SKILLS_HTTP_AUDIT_LOG_PATH=/var/log/awesome-omni-skills/audit.log \
OMNI_SKILLS_HTTP_ALLOWED_ORIGINS=https://app.example.com \
OMNI_SKILLS_HTTP_ALLOWED_IPS=127.0.0.1/32 \
OMNI_SKILLS_HTTP_TRUST_PROXY=loopback \
npx awesome-omni-skills api --port 3333

📡 Endpoints

🏥 Health & Schema

Method Path Description
GET /healthz Health check (unauthenticated)
GET /docs Interactive Swagger UI (OpenAPI 3.1 from openapi.yaml)
GET /admin/runtime Governance and runtime snapshot (admin auth when enabled)

📚 Catalog & Skills

Method Path Description
GET /v1/skills List skills with filters
GET /v1/skills/:id Get individual skill manifest
GET /v1/search Full-text search
GET /v1/compare?ids=id1,id2 Compare multiple skills
GET /v1/bundles List bundles with availability
POST /v1/install/plan Generate an install plan

🔎 List/Search Filters

Filter Example
category ?category=development
tool ?tool=cursor
risk ?risk=safe
sort ?sort=quality|best-practices|level|security|name
order ?order=asc|desc
min_quality ?min_quality=80
min_best_practices ?min_best_practices=60
min_level ?min_level=2
min_security ?min_security=90
validation_status ?validation_status=passed
security_status ?security_status=passed

📦 Install Plan Body

{
  "skill_ids": ["omni-figma"],
  "bundle_ids": ["full-stack"],
  "tools": ["cursor"],
  "target_path": "~/.cursor/skills",
  "dry_run": true
}

📥 Artifact Downloads

Method Path Description
GET /v1/catalog/download Full catalog download
GET /v1/skills/:id/artifacts List skill artifacts
GET /v1/skills/:id/archives List skill archives
GET /v1/skills/:id/downloads All available download links
GET /v1/skills/:id/download/manifest Skill manifest JSON
GET /v1/skills/:id/download/entrypoint Skill SKILL.md
GET /v1/skills/:id/download/artifact?path=<path> Specific artifact
GET /v1/skills/:id/download/archive?format=zip|tar.gz Skill archive
GET /v1/skills/:id/download/archive/signature?format=zip|tar.gz Detached signature
GET /v1/skills/:id/download/archive/checksums SHA-256 checksums

🔗 Link Enrichment

When requests are handled through the API, the server automatically enriches manifests, artifact listings, and install plans with absolute URLs derived from the incoming request origin. This is runtime enrichment, not baked into dist/manifests/*.json.

📋 Install Plan Notes

⚠️ Install plans are previews, not remote writes.

The API never installs onto the caller's machine. It returns:

  • 📌 Selected skill metadata
  • ⚠️ Warnings for missing bundle members
  • 🖥️ Concrete CLI commands to run locally
  • 🔗 Public download URLs when request origin is available

🔌 Relationship to MCP

The MCP server reuses the same public API URLs when configured:

OMNI_SKILLS_API_BASE_URL=http://127.0.0.1:3333 npm run mcp:http

This allows MCP install previews to return concrete manifest and artifact URLs instead of only local repo paths.

🧭 Admin Runtime Snapshot

GET /admin/runtime returns a governance snapshot useful for hosted diagnostics:

  • active auth methods
  • admin-auth status
  • rate-limit window and max
  • CORS allowlist
  • IP allowlist
  • maintenance mode state
  • audit destination and format
  • current catalog totals
  • request ID echoing for traceability