@jigyasudham/veto 0.8.0

package/dist/skills/development/skill-api-design.js

@@ -0,0 +1,313 @@
+// Skill: api-design — REST API design guide with OpenAPI 3.0 skeleton
+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) {
+    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)',
+        ],
+    };
+}
+//# sourceMappingURL=skill-api-design.js.map

package/dist/skills/development/skill-auth.js

@@ -0,0 +1,255 @@
+// Skill: auth — JWT + bcrypt + refresh token implementation guide
+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) {
+    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)',
+        ],
+    };
+}
+//# sourceMappingURL=skill-auth.js.map

package/dist/skills/development/skill-ci-cd.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=skill-ci-cd.js.map