@open-skills-hub/api 1.0.0

package/src/routes/scan.ts

@@ -0,0 +1,428 @@
+/**
+ * Open Skills Hub - Scan Routes
+ * 
+ * Security scanning endpoints using SkillsGuard
+ */
+
+import type { FastifyInstance, FastifyPluginOptions, FastifyRequest, FastifyReply } from 'fastify';
+import { z } from 'zod';
+import {
+  getStorage,
+  getConfig,
+  initScanner,
+  getScanner,
+  generateUUID,
+  now,
+  buildSkillFullName,
+  parseSkillFullName,
+  AppError,
+  ErrorCodes,
+} from '@open-skills-hub/core';
+import type { AuditLog } from '@open-skills-hub/core';
+import { sendSuccess } from '../middleware/error.js';
+import { logger } from '../middleware/logger.js';
+import { optionalAuth, requireAuth } from '../middleware/auth.js';
+import {
+  validateBody,
+  validateParams,
+  validateQuery,
+  SkillNameParamSchema,
+  ScanContentBodySchema,
+  PaginationQuerySchema,
+  IdParamSchema,
+} from '../middleware/validation.js';
+
+// Initialize scanner on first use
+let scannerInitialized = false;
+
+function ensureScannerInitialized() {
+  if (!scannerInitialized) {
+    const config = getConfig().get();
+    initScanner({
+      enabled: config.scanner.enabled,
+      timeout: config.scanner.timeout,
+      maxFileSize: config.scanner.maxFileSize,
+      rulesPath: config.scanner.rulesPath,
+    });
+    scannerInitialized = true;
+  }
+}
+
+/**
+ * Scan content
+ */
+async function scanContent(
+  request: FastifyRequest<{ Body: z.infer<typeof ScanContentBodySchema> }>,
+  reply: FastifyReply
+): Promise<void> {
+  ensureScannerInitialized();
+  
+  const storage = await getStorage();
+  const scanner = getScanner();
+  const { content } = request.body;
+  const userId = request.user?.id;
+
+  // Run the scan
+  const result = await scanner.scan(content);
+
+  // Save scan record and issues to storage
+  await storage.createScanRecord({
+    ...result.record,
+    userId,
+    inputType: 'api',
+  });
+
+  if (result.issues.length > 0) {
+    await storage.createScanIssues(result.issues);
+  }
+
+  // Create audit log
+  const auditLog: AuditLog = {
+    id: generateUUID(),
+    timestamp: now(),
+    eventType: 'scan.completed',
+    actor: {
+      type: request.user?.type ?? 'user',
+      id: userId,
+      username: request.user?.username,
+      ip: request.ip,
+      userAgent: request.headers['user-agent'],
+    },
+    resource: {
+      type: 'skill',
+      id: result.record.id,
+    },
+    action: 'scan',
+    result: 'success',
+    details: {
+      score: result.summary.score,
+      level: result.summary.level,
+      issueCount: result.summary.issueCount,
+      duration: result.record.duration,
+    },
+  };
+  await storage.createAuditLog(auditLog);
+
+  // Log high-risk scans
+  if (result.summary.level === 'high') {
+    const highRiskLog: AuditLog = {
+      id: generateUUID(),
+      timestamp: now(),
+      eventType: 'scan.high_risk',
+      actor: {
+        type: request.user?.type ?? 'user',
+        id: userId,
+        username: request.user?.username,
+        ip: request.ip,
+      },
+      resource: {
+        type: 'skill',
+        id: result.record.id,
+      },
+      action: 'scan',
+      result: 'success',
+      details: {
+        score: result.summary.score,
+        highSeverityIssues: result.summary.issueCount.high,
+        riskCategories: result.summary.riskCategories,
+      },
+    };
+    await storage.createAuditLog(highRiskLog);
+  }
+
+  logger.info('Scan completed', {
+    recordId: result.record.id,
+    score: result.summary.score,
+    level: result.summary.level,
+    issueCount: result.summary.issueCount,
+  });
+
+  sendSuccess(request, reply, {
+    id: result.record.id,
+    score: result.summary.score,
+    level: result.summary.level,
+    issueCount: result.summary.issueCount,
+    issues: result.issues.map(i => ({
+      id: i.id,
+      ruleId: i.ruleId,
+      ruleName: i.ruleName,
+      category: i.ruleCategory,
+      severity: i.severity,
+      line: i.line,
+      column: i.column,
+      content: i.content,
+      message: i.message,
+      suggestion: i.suggestion,
+    })),
+    recommendations: result.summary.recommendations,
+    duration: result.record.duration,
+    scannerVersion: result.record.scannerVersion,
+    rulesApplied: result.record.rulesApplied,
+  });
+}
+
+/**
+ * Quick check content (high-severity only)
+ */
+async function quickCheck(
+  request: FastifyRequest<{ Body: z.infer<typeof ScanContentBodySchema> }>,
+  reply: FastifyReply
+): Promise<void> {
+  ensureScannerInitialized();
+  
+  const scanner = getScanner();
+  const { content } = request.body;
+
+  const result = await scanner.quickCheck(content);
+
+  sendSuccess(request, reply, result);
+}
+
+/**
+ * Get scan records for a skill
+ */
+async function getSkillScans(
+  request: FastifyRequest<{ Params: z.infer<typeof SkillNameParamSchema>; Querystring: z.infer<typeof PaginationQuerySchema> }>,
+  reply: FastifyReply
+): Promise<void> {
+  const storage = await getStorage();
+  const { name } = request.params;
+  const { cursor, limit } = request.query;
+
+  // Parse name
+  const { scope, name: skillName } = parseSkillFullName(name);
+  const fullName = buildSkillFullName(skillName, scope);
+
+  const skill = await storage.getSkillByName(fullName);
+  if (!skill) {
+    throw new AppError(
+      ErrorCodes.SKILL_NOT_FOUND,
+      `Skill '${fullName}' not found`,
+      404
+    );
+  }
+
+  const result = await storage.getScanRecords(skill.id, { cursor, limit });
+
+  sendSuccess(request, reply, result.items, 200, result.pagination);
+}
+
+/**
+ * Get scan record by ID
+ */
+async function getScanRecord(
+  request: FastifyRequest<{ Params: z.infer<typeof IdParamSchema> }>,
+  reply: FastifyReply
+): Promise<void> {
+  const storage = await getStorage();
+  const { id } = request.params;
+
+  const record = await storage.getScanRecordById(id);
+  if (!record) {
+    throw new AppError(
+      ErrorCodes.SKILL_NOT_FOUND,
+      `Scan record '${id}' not found`,
+      404
+    );
+  }
+
+  // Get issues if scan is completed
+  let issues: unknown[] = [];
+  if (record.status === 'completed') {
+    issues = await storage.getScanIssues(id);
+  }
+
+  sendSuccess(request, reply, {
+    ...record,
+    issues,
+  });
+}
+
+/**
+ * Get scan issues for a record
+ */
+async function getScanIssues(
+  request: FastifyRequest<{ Params: z.infer<typeof IdParamSchema> }>,
+  reply: FastifyReply
+): Promise<void> {
+  const storage = await getStorage();
+  const { id } = request.params;
+
+  const record = await storage.getScanRecordById(id);
+  if (!record) {
+    throw new AppError(
+      ErrorCodes.SKILL_NOT_FOUND,
+      `Scan record '${id}' not found`,
+      404
+    );
+  }
+
+  const issues = await storage.getScanIssues(id);
+
+  sendSuccess(request, reply, issues);
+}
+
+/**
+ * Acknowledge an issue
+ */
+async function acknowledgeIssue(
+  request: FastifyRequest<{ Params: z.infer<typeof IdParamSchema>; Body: { reason?: string } }>,
+  reply: FastifyReply
+): Promise<void> {
+  const storage = await getStorage();
+  const { id } = request.params;
+  const { reason } = request.body;
+  const userId = request.user?.id ?? 'unknown';
+
+  const issue = await storage.acknowledgeIssue(id, userId, reason);
+  if (!issue) {
+    throw new AppError(
+      ErrorCodes.SKILL_NOT_FOUND,
+      `Issue '${id}' not found`,
+      404
+    );
+  }
+
+  logger.info('Issue acknowledged', { issueId: id, userId, reason });
+
+  sendSuccess(request, reply, issue);
+}
+
+/**
+ * Get scanner rules
+ */
+async function getScannerRules(
+  request: FastifyRequest,
+  reply: FastifyReply
+): Promise<void> {
+  ensureScannerInitialized();
+  
+  const scanner = getScanner();
+  const rules = scanner.getEnabledRules();
+
+  sendSuccess(request, reply, {
+    version: scanner.getVersion(),
+    rulesCount: rules.length,
+    rules: rules.map(r => ({
+      id: r.id,
+      name: r.name,
+      description: r.description,
+      category: r.category,
+      severity: r.severity,
+      enabled: r.enabled,
+      isBuiltin: r.isBuiltin,
+    })),
+  });
+}
+
+/**
+ * Get scanner statistics
+ */
+async function getScannerStats(
+  request: FastifyRequest,
+  reply: FastifyReply
+): Promise<void> {
+  ensureScannerInitialized();
+  
+  const scanner = getScanner();
+  const rules = scanner.getEnabledRules();
+
+  // Count rules by category and severity
+  const byCategory: Record<string, number> = {};
+  const bySeverity: Record<string, number> = {};
+
+  for (const rule of rules) {
+    byCategory[rule.category] = (byCategory[rule.category] || 0) + 1;
+    bySeverity[rule.severity] = (bySeverity[rule.severity] || 0) + 1;
+  }
+
+  sendSuccess(request, reply, {
+    version: scanner.getVersion(),
+    totalRules: rules.length,
+    enabledRules: rules.filter(r => r.enabled).length,
+    builtinRules: rules.filter(r => r.isBuiltin).length,
+    customRules: rules.filter(r => !r.isBuiltin).length,
+    byCategory,
+    bySeverity,
+  });
+}
+
+export async function scanRoutes(
+  server: FastifyInstance,
+  _opts: FastifyPluginOptions
+): Promise<void> {
+  // Scan content
+  // POST /v1/scan
+  server.post('/', {
+    preHandler: [
+      optionalAuth,
+      validateBody(ScanContentBodySchema),
+    ],
+    handler: scanContent,
+  });
+
+  // Quick check (high-severity only)
+  // POST /v1/scan/quick
+  server.post('/quick', {
+    preHandler: [
+      optionalAuth,
+      validateBody(ScanContentBodySchema),
+    ],
+    handler: quickCheck,
+  });
+
+  // Get scanner rules
+  // GET /v1/scan/rules
+  server.get('/rules', {
+    preHandler: [optionalAuth],
+    handler: getScannerRules,
+  });
+
+  // Get scanner statistics
+  // GET /v1/scan/stats
+  server.get('/stats', {
+    preHandler: [optionalAuth],
+    handler: getScannerStats,
+  });
+
+  // Get scan records for a skill
+  // GET /v1/scan/skill/:name
+  server.get('/skill/:name', {
+    preHandler: [
+      optionalAuth,
+      validateParams(SkillNameParamSchema),
+      validateQuery(PaginationQuerySchema),
+    ],
+    handler: getSkillScans,
+  });
+
+  // Get scan record by ID
+  // GET /v1/scan/:id
+  server.get('/:id', {
+    preHandler: [
+      optionalAuth,
+      validateParams(IdParamSchema),
+    ],
+    handler: getScanRecord,
+  });
+
+  // Get issues for a scan record
+  // GET /v1/scan/:id/issues
+  server.get('/:id/issues', {
+    preHandler: [
+      optionalAuth,
+      validateParams(IdParamSchema),
+    ],
+    handler: getScanIssues,
+  });
+
+  // Acknowledge an issue
+  // POST /v1/scan/issues/:id/acknowledge
+  server.post('/issues/:id/acknowledge', {
+    preHandler: [
+      requireAuth,
+      validateParams(IdParamSchema),
+    ],
+    handler: acknowledgeIssue,
+  });
+}

package/src/routes/search.ts

@@ -0,0 +1,51 @@
+/**
+ * Open Skills Hub - Search Routes
+ */
+
+import type { FastifyInstance, FastifyPluginOptions, FastifyRequest, FastifyReply } from 'fastify';
+import { searchSkills, type SearchQuery } from '../controllers/skills.js';
+import { optionalAuth } from '../middleware/auth.js';
+import { validateQuery, SearchQuerySchema } from '../middleware/validation.js';
+
+export async function searchRoutes(
+  server: FastifyInstance,
+  _opts: FastifyPluginOptions
+): Promise<void> {
+  // Full-text search
+  // GET /v1/search?q=...&category=...&sort=...
+  server.get('/', {
+    preHandler: [
+      optionalAuth,
+      validateQuery(SearchQuerySchema),
+    ],
+    handler: searchSkills as (request: FastifyRequest, reply: FastifyReply) => Promise<void>,
+  });
+
+  // Search by category (convenience endpoint)
+  // GET /v1/search/category/:category
+  server.get('/category/:category', {
+    preHandler: [
+      optionalAuth,
+    ],
+    handler: async (request, reply) => {
+      const { category } = request.params as { category: string };
+      // Forward to main search with category filter
+      (request.query as SearchQuery).category = category;
+      return (searchSkills as (request: FastifyRequest, reply: FastifyReply) => Promise<void>)(request, reply);
+    },
+  });
+
+  // Search by author (convenience endpoint)
+  // GET /v1/search/author/:author
+  server.get('/author/:author', {
+    preHandler: [
+      optionalAuth,
+    ],
+    handler: async (request, reply) => {
+      const { author } = request.params as { author: string };
+      // Forward to main search with author filter
+      (request.query as SearchQuery).author = author;
+      return (searchSkills as (request: FastifyRequest, reply: FastifyReply) => Promise<void>)(request, reply);
+    },
+  });
+}

package/src/routes/skills.ts

@@ -0,0 +1,102 @@
+/**
+ * Open Skills Hub - Skills Routes
+ */
+
+import type { FastifyInstance, FastifyPluginOptions } from 'fastify';
+import {
+  searchSkills,
+  getSkillByName,
+  getSkillContent,
+  createSkill,
+  updateSkill,
+  deleteSkill,
+  getDerivedSkills,
+} from '../controllers/skills.js';
+import { optionalAuth, requireAuth } from '../middleware/auth.js';
+import {
+  validateBody,
+  validateParams,
+  validateQuery,
+  SkillNameParamSchema,
+  SearchQuerySchema,
+  CreateSkillBodySchema,
+  UpdateSkillBodySchema,
+  PaginationQuerySchema,
+} from '../middleware/validation.js';
+
+export async function skillsRoutes(
+  server: FastifyInstance,
+  _opts: FastifyPluginOptions
+): Promise<void> {
+  // Search skills
+  // GET /v1/skills?q=...&category=...&author=...
+  server.get('/', {
+    preHandler: [
+      optionalAuth,
+      validateQuery(SearchQuerySchema),
+    ],
+    handler: searchSkills,
+  });
+
+  // Get skill by name
+  // GET /v1/skills/:name
+  server.get('/:name', {
+    preHandler: [
+      optionalAuth,
+      validateParams(SkillNameParamSchema),
+    ],
+    handler: getSkillByName,
+  });
+
+  // Get skill content (fetch-on-use)
+  // GET /v1/skills/:name/content?version=...
+  server.get('/:name/content', {
+    preHandler: [
+      optionalAuth,
+      validateParams(SkillNameParamSchema),
+    ],
+    handler: getSkillContent,
+  });
+
+  // Create/publish a new skill
+  // POST /v1/skills
+  server.post('/', {
+    preHandler: [
+      requireAuth,
+      validateBody(CreateSkillBodySchema),
+    ],
+    handler: createSkill,
+  });
+
+  // Update skill metadata
+  // PATCH /v1/skills/:name
+  server.patch('/:name', {
+    preHandler: [
+      requireAuth,
+      validateParams(SkillNameParamSchema),
+      validateBody(UpdateSkillBodySchema),
+    ],
+    handler: updateSkill,
+  });
+
+  // Delete skill
+  // DELETE /v1/skills/:name?hard=true
+  server.delete('/:name', {
+    preHandler: [
+      requireAuth,
+      validateParams(SkillNameParamSchema),
+    ],
+    handler: deleteSkill,
+  });
+
+  // Get derived skills
+  // GET /v1/skills/:name/derived
+  server.get('/:name/derived', {
+    preHandler: [
+      optionalAuth,
+      validateParams(SkillNameParamSchema),
+      validateQuery(PaginationQuerySchema),
+    ],
+    handler: getDerivedSkills,
+  });
+}

package/src/routes/versions.ts

@@ -0,0 +1,91 @@
+/**
+ * Open Skills Hub - Versions Routes
+ */
+
+import type { FastifyInstance, FastifyPluginOptions } from 'fastify';
+import { z } from 'zod';
+import {
+  getVersions,
+  getVersion,
+  publishVersion,
+  deprecateVersion,
+  deleteVersion,
+} from '../controllers/versions.js';
+import { optionalAuth, requireAuth } from '../middleware/auth.js';
+import {
+  validateBody,
+  validateParams,
+  validateQuery,
+  SkillNameParamSchema,
+  SkillVersionParamSchema,
+  PublishVersionBodySchema,
+  PaginationQuerySchema,
+} from '../middleware/validation.js';
+
+// Extended query schema for versions
+const VersionsQuerySchema = PaginationQuerySchema.extend({
+  includeDeprecated: z.string().optional(),
+});
+
+// Deprecate body schema
+const DeprecateBodySchema = z.object({
+  message: z.string().optional(),
+});
+
+export async function versionsRoutes(
+  server: FastifyInstance,
+  _opts: FastifyPluginOptions
+): Promise<void> {
+  // Get all versions of a skill
+  // GET /v1/skills/:name/versions
+  server.get('/:name/versions', {
+    preHandler: [
+      optionalAuth,
+      validateParams(SkillNameParamSchema),
+      validateQuery(VersionsQuerySchema),
+    ],
+    handler: getVersions,
+  });
+
+  // Get a specific version
+  // GET /v1/skills/:name/versions/:version
+  server.get('/:name/versions/:version', {
+    preHandler: [
+      optionalAuth,
+      validateParams(SkillVersionParamSchema),
+    ],
+    handler: getVersion,
+  });
+
+  // Publish a new version
+  // POST /v1/skills/:name/versions
+  server.post('/:name/versions', {
+    preHandler: [
+      requireAuth,
+      validateParams(SkillNameParamSchema),
+      validateBody(PublishVersionBodySchema),
+    ],
+    handler: publishVersion,
+  });
+
+  // Deprecate a version
+  // POST /v1/skills/:name/versions/:version/deprecate
+  server.post('/:name/versions/:version/deprecate', {
+    preHandler: [
+      requireAuth,
+      validateParams(SkillVersionParamSchema),
+      validateBody(DeprecateBodySchema),
+    ],
+    handler: deprecateVersion,
+  });
+
+  // Delete/yank a version
+  // DELETE /v1/skills/:name/versions/:version
+  server.delete('/:name/versions/:version', {
+    preHandler: [
+      requireAuth,
+      validateParams(SkillVersionParamSchema),
+    ],
+    handler: deleteVersion,
+  });
+}