@jigyasudham/veto 0.8.2 → 1.0.0

package/src/skills/development/skill-api-design.ts

@@ -1,329 +0,0 @@
-// Skill: api-design — REST API design guide with OpenAPI 3.0 skeleton
-
-export interface SkillInput {
-  task: string;
-  context?: string;
-  options?: Record<string, unknown>;
-}
-
-export interface SkillOutput {
-  skill: string;
-  template?: string;
-  checklist: string[];
-  patterns: string[];
-  gotchas: string[];
-  resources: string[];
-}
-
-const TEMPLATE = `
-openapi: 3.0.3
-info:
-  title: My API
-  description: >
-    RESTful API for My Application.
-    All endpoints require a Bearer token unless marked as public.
-  version: 1.0.0
-  contact:
-    name: API Support
-    email: api@example.com
-
-servers:
-  - url: https://api.example.com/v1
-    description: Production
-  - url: http://localhost:3000/v1
-    description: Local development
-
-security:
-  - BearerAuth: []
-
-# ── Components ─────────────────────────────────────────────────────────────
-components:
-  securitySchemes:
-    BearerAuth:
-      type: http
-      scheme: bearer
-      bearerFormat: JWT
-
-  schemas:
-    # Pagination wrapper
-    PaginatedResponse:
-      type: object
-      required: [data, meta]
-      properties:
-        data:
-          type: array
-          items: {}
-        meta:
-          type: object
-          required: [total, page, pageSize, totalPages]
-          properties:
-            total:       { type: integer, example: 142 }
-            page:        { type: integer, example: 1 }
-            pageSize:    { type: integer, example: 20 }
-            totalPages:  { type: integer, example: 8 }
-
-    # Error envelope
-    ErrorResponse:
-      type: object
-      required: [error]
-      properties:
-        error:
-          type: object
-          required: [code, message]
-          properties:
-            code:    { type: string,  example: VALIDATION_ERROR }
-            message: { type: string,  example: "name must not be empty" }
-            details: { type: array, items: { type: string } }
-
-    # Resource example
-    Item:
-      type: object
-      required: [id, name, userId, createdAt, updatedAt]
-      properties:
-        id:          { type: string, format: uuid }
-        name:        { type: string, minLength: 1, maxLength: 100 }
-        description: { type: string, maxLength: 500 }
-        userId:      { type: string, format: uuid }
-        createdAt:   { type: string, format: date-time }
-        updatedAt:   { type: string, format: date-time }
-
-    CreateItemRequest:
-      type: object
-      required: [name]
-      properties:
-        name:        { type: string, minLength: 1, maxLength: 100 }
-        description: { type: string, maxLength: 500 }
-
-    UpdateItemRequest:
-      type: object
-      minProperties: 1
-      properties:
-        name:        { type: string, minLength: 1, maxLength: 100 }
-        description: { type: string, maxLength: 500 }
-
-  parameters:
-    ItemId:
-      name: id
-      in: path
-      required: true
-      schema: { type: string, format: uuid }
-    PageParam:
-      name: page
-      in: query
-      schema: { type: integer, minimum: 1, default: 1 }
-    PageSizeParam:
-      name: pageSize
-      in: query
-      schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
-    SortParam:
-      name: sort
-      in: query
-      schema: { type: string, enum: [createdAt, updatedAt, name], default: createdAt }
-    OrderParam:
-      name: order
-      in: query
-      schema: { type: string, enum: [asc, desc], default: desc }
-
-  responses:
-    Unauthorized:
-      description: Missing or invalid authentication token
-      content:
-        application/json:
-          schema: { $ref: '#/components/schemas/ErrorResponse' }
-    Forbidden:
-      description: Authenticated but not authorised to access this resource
-      content:
-        application/json:
-          schema: { $ref: '#/components/schemas/ErrorResponse' }
-    NotFound:
-      description: Resource not found
-      content:
-        application/json:
-          schema: { $ref: '#/components/schemas/ErrorResponse' }
-    UnprocessableEntity:
-      description: Validation error in request body
-      content:
-        application/json:
-          schema: { $ref: '#/components/schemas/ErrorResponse' }
-    TooManyRequests:
-      description: Rate limit exceeded
-      headers:
-        Retry-After: { schema: { type: integer } }
-      content:
-        application/json:
-          schema: { $ref: '#/components/schemas/ErrorResponse' }
-
-# ── Paths ──────────────────────────────────────────────────────────────────
-paths:
-  /items:
-    get:
-      operationId: listItems
-      summary: List items belonging to the authenticated user
-      tags: [Items]
-      parameters:
-        - $ref: '#/components/parameters/PageParam'
-        - $ref: '#/components/parameters/PageSizeParam'
-        - $ref: '#/components/parameters/SortParam'
-        - $ref: '#/components/parameters/OrderParam'
-      responses:
-        '200':
-          description: Paginated list of items
-          content:
-            application/json:
-              schema:
-                allOf:
-                  - $ref: '#/components/schemas/PaginatedResponse'
-                  - properties:
-                      data:
-                        type: array
-                        items: { $ref: '#/components/schemas/Item' }
-        '401': { $ref: '#/components/responses/Unauthorized' }
-        '429': { $ref: '#/components/responses/TooManyRequests' }
-
-    post:
-      operationId: createItem
-      summary: Create a new item
-      tags: [Items]
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema: { $ref: '#/components/schemas/CreateItemRequest' }
-      responses:
-        '201':
-          description: Item created
-          headers:
-            Location: { schema: { type: string }, description: URL of the created item }
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  data: { $ref: '#/components/schemas/Item' }
-        '401': { $ref: '#/components/responses/Unauthorized' }
-        '422': { $ref: '#/components/responses/UnprocessableEntity' }
-
-  /items/{id}:
-    parameters:
-      - $ref: '#/components/parameters/ItemId'
-
-    get:
-      operationId: getItem
-      summary: Get a single item by ID
-      tags: [Items]
-      responses:
-        '200':
-          description: Item found
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  data: { $ref: '#/components/schemas/Item' }
-        '401': { $ref: '#/components/responses/Unauthorized' }
-        '403': { $ref: '#/components/responses/Forbidden' }
-        '404': { $ref: '#/components/responses/NotFound' }
-
-    patch:
-      operationId: updateItem
-      summary: Partially update an item (only provided fields are changed)
-      tags: [Items]
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema: { $ref: '#/components/schemas/UpdateItemRequest' }
-      responses:
-        '200':
-          description: Item updated
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  data: { $ref: '#/components/schemas/Item' }
-        '401': { $ref: '#/components/responses/Unauthorized' }
-        '403': { $ref: '#/components/responses/Forbidden' }
-        '404': { $ref: '#/components/responses/NotFound' }
-        '422': { $ref: '#/components/responses/UnprocessableEntity' }
-
-    delete:
-      operationId: deleteItem
-      summary: Delete an item
-      tags: [Items]
-      responses:
-        '204':
-          description: Item deleted — no content returned
-        '401': { $ref: '#/components/responses/Unauthorized' }
-        '403': { $ref: '#/components/responses/Forbidden' }
-        '404': { $ref: '#/components/responses/NotFound' }
-
-  /health:
-    get:
-      operationId: getHealth
-      summary: Health check — no authentication required
-      tags: [System]
-      security: []
-      responses:
-        '200':
-          description: Service is healthy
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  status: { type: string, example: ok }
-                  uptime: { type: number, example: 12345.6 }
-`.trim();
-
-export function run(input: SkillInput): SkillOutput {
-  return {
-    skill: 'api-design',
-    template: TEMPLATE,
-    checklist: [
-      'Choose a consistent resource naming convention: plural nouns, kebab-case (e.g., /user-profiles)',
-      'Version the API in the URL path: /v1/resource (not Accept header for most APIs)',
-      'Use correct HTTP methods: GET (read), POST (create), PUT (replace), PATCH (partial update), DELETE (remove)',
-      'Use correct HTTP status codes: 200 OK, 201 Created, 204 No Content, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable Entity, 429 Too Many Requests, 500 Internal Server Error',
-      'Always return a consistent error envelope: { error: { code, message, details? } }',
-      'Wrap list responses in { data: [], meta: { total, page, pageSize, totalPages } }',
-      'Add Location header on 201 Created pointing to the new resource URL',
-      'Implement cursor-based pagination for large, frequently-updated datasets',
-      'Support filtering via query parameters: ?status=active&userId=xxx',
-      'Support sorting via ?sort=createdAt&order=desc',
-      'Set authentication via Authorization: Bearer <token> header (not query param)',
-      'Define all schemas in OpenAPI components/schemas and $ref them — no inline duplication',
-      'Document every response code, including error responses, in the OpenAPI spec',
-      'Apply rate limiting headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset',
-      'Set security headers: CORS, Content-Type: application/json, X-Content-Type-Options: nosniff',
-      'Use idempotency keys for POST endpoints that create resources (Idempotency-Key header)',
-      'Do not nest resources more than 2 levels deep: /users/{id}/items, not /users/{id}/orders/{id}/items/{id}/tags',
-      'Return 204 with no body for successful DELETE, not 200 with empty object',
-      'Use ISO 8601 for all date/time fields: "2024-01-15T10:30:00Z"',
-      'Generate an SDK or client library from the OpenAPI spec using openapi-generator',
-    ],
-    patterns: [
-      'Resource-oriented design: endpoints represent nouns, HTTP methods are the verbs',
-      'Envelope pattern: { data: T, meta: M } for lists; { data: T } for single resources',
-      'Error code + message pattern: machine-readable code + human-readable message',
-      'Consistent pagination: cursor-based for feeds, offset/page for admin views',
-      'OpenAPI-first design: write the spec before implementing, validate implementation against it',
-    ],
-    gotchas: [
-      'Using GET with a request body for search — use POST /resource/search or query params instead',
-      'Returning 200 with { success: false } — use the correct status code, not always 200',
-      'Inconsistent pluralisation: /user vs /users — pick one convention and apply everywhere',
-      'Exposing internal IDs (auto-increment integers) — use UUIDs to prevent IDOR and enumeration',
-      'Not documenting rate limits in the spec — clients cannot implement retry logic without this',
-      'CORS misconfiguration: wildcard origin with credentials:true is invalid and silently ignored by browsers',
-      'Changing URL structure or removing fields without a deprecation period — breaks existing clients',
-    ],
-    resources: [
-      'https://spec.openapis.org/oas/v3.0.3',
-      'https://cloud.google.com/apis/design',
-      'https://cheatsheetseries.owasp.org/cheatsheets/REST_Security_Cheat_Sheet.html',
-      'https://restfulapi.net/',
-      'https://www.rfc-editor.org/rfc/rfc9457 (Problem Details for HTTP APIs)',
-    ],
-  };
-}

package/src/skills/development/skill-auth.ts

@@ -1,271 +0,0 @@
-// Skill: auth — JWT + bcrypt + refresh token implementation guide
-
-export interface SkillInput {
-  task: string;
-  context?: string;
-  options?: Record<string, unknown>;
-}
-
-export interface SkillOutput {
-  skill: string;
-  template?: string;
-  checklist: string[];
-  patterns: string[];
-  gotchas: string[];
-  resources: string[];
-}
-
-const TEMPLATE = `
-// ── Types (src/models/auth.ts) ────────────────────────────────────────────
-export interface User {
-  id: string;
-  email: string;
-  passwordHash: string;
-  role: 'admin' | 'user';
-  failedLoginAttempts: number;
-  lockedUntil?: Date | null;
-  createdAt: Date;
-}
-
-export interface TokenPair {
-  accessToken: string;   // short-lived, stateless JWT
-  refreshToken: string;  // long-lived, stored in DB
-}
-
-// ── Token utilities (src/utils/tokens.ts) ────────────────────────────────
-import jwt from 'jsonwebtoken';
-import crypto from 'crypto';
-
-const ACCESS_SECRET = process.env.JWT_ACCESS_SECRET!;   // 256-bit random
-const REFRESH_SECRET = process.env.JWT_REFRESH_SECRET!; // separate secret
-const ACCESS_TTL = '15m';
-const REFRESH_TTL = '7d';
-
-export function signAccessToken(userId: string, role: string): string {
-  return jwt.sign({ sub: userId, role }, ACCESS_SECRET, {
-    expiresIn: ACCESS_TTL,
-    algorithm: 'HS256',
-  });
-}
-
-export function verifyAccessToken(token: string): { sub: string; role: string } {
-  return jwt.verify(token, ACCESS_SECRET, { algorithms: ['HS256'] }) as { sub: string; role: string };
-}
-
-export function generateRefreshToken(): string {
-  return crypto.randomBytes(64).toString('hex'); // 512 bits of entropy
-}
-
-// ── Auth service (src/services/auth.service.ts) ───────────────────────────
-import bcrypt from 'bcrypt';
-
-const BCRYPT_ROUNDS = 12;
-const MAX_ATTEMPTS = 5;
-const LOCKOUT_MINUTES = 30;
-
-export class AuthService {
-  constructor(
-    private readonly userRepo: UserRepository,
-    private readonly tokenRepo: RefreshTokenRepository,
-  ) {}
-
-  async register(email: string, password: string): Promise<User> {
-    const existing = await this.userRepo.findByEmail(email);
-    if (existing) throw new ConflictError('Email already registered');
-    const passwordHash = await bcrypt.hash(password, BCRYPT_ROUNDS);
-    return this.userRepo.create({ email: email.toLowerCase().trim(), passwordHash });
-  }
-
-  async login(email: string, password: string): Promise<TokenPair> {
-    const user = await this.userRepo.findByEmail(email.toLowerCase().trim());
-    if (!user) throw new UnauthorizedError('Invalid credentials');
-
-    if (user.lockedUntil && user.lockedUntil > new Date()) {
-      throw new UnauthorizedError('Account locked. Check your email to unlock.');
-    }
-
-    const valid = await bcrypt.compare(password, user.passwordHash);
-    if (!valid) {
-      await this.recordFailedAttempt(user);
-      throw new UnauthorizedError('Invalid credentials');
-    }
-
-    await this.userRepo.resetFailedAttempts(user.id);
-    return this.issueTokenPair(user.id, user.role);
-  }
-
-  async refresh(rawRefreshToken: string): Promise<TokenPair> {
-    const tokenHash = hashToken(rawRefreshToken);
-    const stored = await this.tokenRepo.findByHash(tokenHash);
-    if (!stored || stored.revokedAt || stored.expiresAt < new Date()) {
-      throw new UnauthorizedError('Invalid or expired refresh token');
-    }
-    // Rotate: revoke old, issue new
-    await this.tokenRepo.revoke(stored.id);
-    return this.issueTokenPair(stored.userId, stored.role);
-  }
-
-  async logout(rawRefreshToken: string): Promise<void> {
-    const tokenHash = hashToken(rawRefreshToken);
-    const stored = await this.tokenRepo.findByHash(tokenHash);
-    if (stored) await this.tokenRepo.revoke(stored.id);
-  }
-
-  private async issueTokenPair(userId: string, role: string): Promise<TokenPair> {
-    const rawRefreshToken = generateRefreshToken();
-    await this.tokenRepo.create({
-      userId,
-      tokenHash: hashToken(rawRefreshToken),
-      role,
-      expiresAt: addDays(new Date(), 7),
-    });
-    return {
-      accessToken: signAccessToken(userId, role),
-      refreshToken: rawRefreshToken,
-    };
-  }
-
-  private async recordFailedAttempt(user: User): Promise<void> {
-    const attempts = user.failedLoginAttempts + 1;
-    if (attempts >= MAX_ATTEMPTS) {
-      const lockedUntil = addMinutes(new Date(), LOCKOUT_MINUTES);
-      await this.userRepo.lockAccount(user.id, lockedUntil);
-      // TODO: send unlock email
-    } else {
-      await this.userRepo.incrementFailedAttempts(user.id);
-    }
-  }
-}
-
-// ── Auth middleware (src/middleware/auth.ts) ───────────────────────────────
-import { Request, Response, NextFunction } from 'express';
-
-export function requireAuth(req: Request, res: Response, next: NextFunction): void {
-  const header = req.headers.authorization;
-  if (!header?.startsWith('Bearer ')) {
-    res.status(401).json({ error: 'Missing or malformed Authorization header' });
-    return;
-  }
-  try {
-    const payload = verifyAccessToken(header.slice(7));
-    req.user = { id: payload.sub, role: payload.role };
-    next();
-  } catch {
-    res.status(401).json({ error: 'Invalid or expired access token' });
-  }
-}
-
-export function requireRole(role: string) {
-  return (req: Request, res: Response, next: NextFunction): void => {
-    if (req.user?.role !== role) {
-      res.status(403).json({ error: 'Insufficient permissions' });
-      return;
-    }
-    next();
-  };
-}
-
-// ── Auth routes (src/routes/auth.ts) ─────────────────────────────────────
-import { Router } from 'express';
-import { z } from 'zod';
-import rateLimit from 'express-rate-limit';
-
-const authLimiter = rateLimit({ windowMs: 15 * 60 * 1000, max: 10, standardHeaders: true });
-
-const RegisterSchema = z.object({
-  email: z.string().email().max(255),
-  password: z.string().min(12).max(128),
-});
-
-const LoginSchema = RegisterSchema;
-
-export function createAuthRouter(service: AuthService): Router {
-  const router = Router();
-  router.use(authLimiter);
-
-  router.post('/register', validate(RegisterSchema), async (req, res) => {
-    const user = await service.register(req.body.email, req.body.password);
-    res.status(201).json({ data: { id: user.id, email: user.email } });
-  });
-
-  router.post('/login', validate(LoginSchema), async (req, res) => {
-    const tokens = await service.login(req.body.email, req.body.password);
-    res
-      .cookie('refreshToken', tokens.refreshToken, {
-        httpOnly: true, secure: true, sameSite: 'strict', maxAge: 7 * 24 * 60 * 60 * 1000,
-      })
-      .json({ data: { accessToken: tokens.accessToken } });
-  });
-
-  router.post('/refresh', async (req, res) => {
-    const raw = req.cookies?.refreshToken;
-    if (!raw) { res.status(401).json({ error: 'No refresh token' }); return; }
-    const tokens = await service.refresh(raw);
-    res
-      .cookie('refreshToken', tokens.refreshToken, {
-        httpOnly: true, secure: true, sameSite: 'strict', maxAge: 7 * 24 * 60 * 60 * 1000,
-      })
-      .json({ data: { accessToken: tokens.accessToken } });
-  });
-
-  router.post('/logout', async (req, res) => {
-    const raw = req.cookies?.refreshToken;
-    if (raw) await service.logout(raw);
-    res.clearCookie('refreshToken').status(204).send();
-  });
-
-  return router;
-}
-`.trim();
-
-export function run(input: SkillInput): SkillOutput {
-  return {
-    skill: 'auth',
-    template: TEMPLATE,
-    checklist: [
-      'Install: npm install bcrypt jsonwebtoken cookie-parser express-rate-limit && npm install -D @types/bcrypt @types/jsonwebtoken @types/cookie-parser',
-      'Generate two separate 256-bit secrets: JWT_ACCESS_SECRET and JWT_REFRESH_SECRET via crypto.randomBytes(32).toString("hex")',
-      'Store both secrets in environment variables; never hardcode them',
-      'Implement User model with passwordHash (never password), failedLoginAttempts, lockedUntil fields',
-      'Implement RefreshToken model with userId, tokenHash (SHA-256 of raw token), expiresAt, revokedAt',
-      'Set bcrypt cost factor to 12; adjust up if server can handle the latency',
-      'Set access token TTL to 15 minutes; set refresh token TTL to 7 days',
-      'Always call jwt.verify with explicit { algorithms: ["HS256"] } — never allow alg negotiation',
-      'Implement refresh token rotation: revoke old token, issue new token on every /refresh call',
-      'Store the SHA-256 hash of the refresh token in DB, never the raw value',
-      'Deliver access token in response body; deliver refresh token in httpOnly Secure SameSite=Strict cookie',
-      'Apply express-rate-limit (10 req/15 min) to all auth endpoints',
-      'Implement account lockout: after 5 failures, lock for 30 minutes and send unlock email',
-      'Normalise email input: .toLowerCase().trim() before lookup or storage',
-      'Return identical error messages for invalid credentials regardless of whether user exists (prevents enumeration)',
-      'Implement /logout that revokes refresh token from DB and clears cookie',
-      'Implement password reset: generate a single-use HMAC token, send via email, expire in 1 hour',
-      'Log every auth event (login success/fail, logout, token refresh, lockout) with userId, IP, user-agent',
-      'Write unit tests for AuthService mocking repositories',
-      'Write integration tests: register → login → refresh → logout → verify refresh fails after logout',
-    ],
-    patterns: [
-      'Stateless access token + stateful refresh token hybrid',
-      'Refresh token rotation with database revocation',
-      'httpOnly cookie for refresh token (XSS-safe delivery)',
-      'Hash-before-store for refresh tokens (never store raw token)',
-      'Rate limiter middleware applied at router level, not per-route',
-    ],
-    gotchas: [
-      'Not rotating refresh tokens on use — a stolen refresh token can be used indefinitely',
-      'Accepting jwt.verify without specifying algorithms — "alg":"none" bypass attack',
-      'Storing refresh tokens in localStorage — immediately exposed to any XSS vulnerability',
-      'Using a short bcrypt salt rounds (< 10) — trivial brute force offline after DB leak',
-      'Reusing the same secret for access and refresh tokens — compromise of one breaks both',
-      'Not invalidating access tokens on logout — they remain valid until expiry (15 min window)',
-      'Not sending identical error messages for bad username vs bad password — enables enumeration',
-    ],
-    resources: [
-      'https://www.npmjs.com/package/jsonwebtoken',
-      'https://www.npmjs.com/package/bcrypt',
-      'https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html',
-      'https://cheatsheetseries.owasp.org/cheatsheets/JSON_Web_Token_for_Java_Cheat_Sheet.html',
-      'https://datatracker.ietf.org/doc/html/rfc6749 (OAuth 2.0)',
-    ],
-  };
-}