@patricio0312rev/skillset 0.1.0

package/templates/backend/service-layer-extractor/ SKILL.md

@@ -0,0 +1,269 @@
+---
+name: service-layer-extractor
+description: Refactors route handlers into service layer with clean boundaries, dependency injection, testability, and separation of concerns. Provides service interfaces, folder structure, testing strategy, and migration plan. Use when refactoring "fat controllers", "business logic", "service layer", or "architecture cleanup".
+---
+
+# Service Layer Extractor
+
+Extract business logic from controllers into a testable service layer.
+
+## Architecture Layers
+
+```
+routes/          → Define endpoints, parse requests
+controllers/     → Validate input, call services, format responses
+services/        → Business logic, orchestration
+repositories/    → Database queries
+models/          → Data structures
+```
+
+## Before: Fat Controller
+
+```typescript
+// ❌ Business logic mixed with HTTP concerns
+router.post("/users", async (req, res) => {
+  try {
+    // Validation
+    if (!req.body.email) {
+      return res.status(400).json({ error: "Email required" });
+    }
+
+    // Check duplicate
+    const existing = await db.query("SELECT * FROM users WHERE email = $1", [
+      req.body.email,
+    ]);
+    if (existing.rows.length > 0) {
+      return res.status(409).json({ error: "Email already exists" });
+    }
+
+    // Hash password
+    const hashedPassword = await bcrypt.hash(req.body.password, 10);
+
+    // Create user
+    const result = await db.query(
+      "INSERT INTO users (email, password, name) VALUES ($1, $2, $3) RETURNING *",
+      [req.body.email, hashedPassword, req.body.name]
+    );
+
+    // Send welcome email
+    await sendEmail(req.body.email, "Welcome!", "Thanks for joining");
+
+    res.status(201).json(result.rows[0]);
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+```
+
+## After: Service Layer
+
+```typescript
+// ✅ Separated concerns
+
+// services/user.service.ts
+export class UserService {
+  constructor(
+    private userRepository: UserRepository,
+    private emailService: EmailService
+  ) {}
+
+  async createUser(dto: CreateUserDto): Promise<User> {
+    // Business logic only
+    const existing = await this.userRepository.findByEmail(dto.email);
+    if (existing) {
+      throw new ConflictError("Email already exists");
+    }
+
+    const hashedPassword = await bcrypt.hash(dto.password, 10);
+
+    const user = await this.userRepository.create({
+      ...dto,
+      password: hashedPassword,
+    });
+
+    await this.emailService.sendWelcome(user.email);
+
+    return user;
+  }
+}
+
+// controllers/user.controller.ts
+export class UserController {
+  constructor(private userService: UserService) {}
+
+  create = asyncHandler(async (req, res) => {
+    const user = await this.userService.createUser(req.body);
+    res.status(201).json({ success: true, data: user });
+  });
+}
+
+// repositories/user.repository.ts
+export class UserRepository {
+  async create(data: CreateUserData): Promise<User> {
+    const result = await db.query(
+      "INSERT INTO users (email, password, name) VALUES ($1, $2, $3) RETURNING *",
+      [data.email, data.password, data.name]
+    );
+    return result.rows[0];
+  }
+
+  async findByEmail(email: string): Promise<User | null> {
+    const result = await db.query("SELECT * FROM users WHERE email = $1", [
+      email,
+    ]);
+    return result.rows[0] || null;
+  }
+}
+```
+
+## Dependency Injection
+
+```typescript
+// container.ts (using tsyringe or manual)
+import { UserService } from "./services/user.service";
+import { UserRepository } from "./repositories/user.repository";
+import { EmailService } from "./services/email.service";
+
+export class Container {
+  private static instances = new Map();
+
+  static get<T>(constructor: new (...args: any[]) => T): T {
+    if (!this.instances.has(constructor)) {
+      // Create dependencies
+      const deps = this.resolveDependencies(constructor);
+      this.instances.set(constructor, new constructor(...deps));
+    }
+    return this.instances.get(constructor);
+  }
+
+  private static resolveDependencies(constructor: any): any[] {
+    // Resolve constructor dependencies
+    return [];
+  }
+}
+
+// Usage
+const userService = Container.get(UserService);
+```
+
+## Testing Services
+
+```typescript
+// user.service.test.ts
+describe("UserService", () => {
+  let service: UserService;
+  let mockRepository: jest.Mocked<UserRepository>;
+  let mockEmailService: jest.Mocked<EmailService>;
+
+  beforeEach(() => {
+    mockRepository = {
+      create: jest.fn(),
+      findByEmail: jest.fn(),
+    } as any;
+
+    mockEmailService = {
+      sendWelcome: jest.fn(),
+    } as any;
+
+    service = new UserService(mockRepository, mockEmailService);
+  });
+
+  it("creates user successfully", async () => {
+    mockRepository.findByEmail.mockResolvedValue(null);
+    mockRepository.create.mockResolvedValue({
+      id: "1",
+      email: "test@example.com",
+    });
+
+    const user = await service.createUser({
+      email: "test@example.com",
+      password: "password123",
+      name: "Test User",
+    });
+
+    expect(user.id).toBe("1");
+    expect(mockEmailService.sendWelcome).toHaveBeenCalled();
+  });
+
+  it("throws error if email exists", async () => {
+    mockRepository.findByEmail.mockResolvedValue({ id: "1" } as User);
+
+    await expect(
+      service.createUser({
+        email: "existing@example.com",
+        password: "pass",
+        name: "Test",
+      })
+    ).rejects.toThrow(ConflictError);
+  });
+});
+```
+
+## Folder Structure
+
+```
+src/
+├── routes/
+│   └── users.routes.ts
+├── controllers/
+│   └── user.controller.ts
+├── services/
+│   ├── user.service.ts
+│   ├── email.service.ts
+│   └── payment.service.ts
+├── repositories/
+│   └── user.repository.ts
+├── models/
+│   └── user.model.ts
+├── types/
+│   └── user.types.ts
+└── middleware/
+    └── validate.ts
+```
+
+## Migration Strategy
+
+```markdown
+## Phase 1: Create Service Layer (Week 1-2)
+
+- [ ] Create service classes
+- [ ] Move business logic to services
+- [ ] Keep controllers thin
+- [ ] No breaking changes
+
+## Phase 2: Add Tests (Week 3-4)
+
+- [ ] Write service unit tests
+- [ ] Mock dependencies
+- [ ] Achieve 80%+ coverage
+
+## Phase 3: Extract Repositories (Week 5-6)
+
+- [ ] Create repository layer
+- [ ] Move DB queries from services
+- [ ] Services depend on repositories
+
+## Phase 4: Dependency Injection (Week 7-8)
+
+- [ ] Set up DI container
+- [ ] Remove manual instantiation
+- [ ] Wire up dependencies
+```
+
+## Benefits
+
+- **Testability**: Services testable without HTTP
+- **Reusability**: Logic reused across endpoints
+- **Separation**: Clear boundaries between layers
+- **Maintainability**: Easier to locate and modify logic
+
+## Output Checklist
+
+- [ ] Service classes created
+- [ ] Business logic extracted from controllers
+- [ ] Repository layer for data access
+- [ ] Dependency injection setup
+- [ ] Unit tests for services
+- [ ] Folder structure reorganized
+- [ ] Migration plan documented
+- [ ] Team trained on new patterns

package/templates/backend/webhook-receiver-hardener/ SKILL.md

@@ -0,0 +1,211 @@
+---
+name: webhook-receiver-hardener
+description: Secures webhook receivers with signature verification, retry handling, deduplication, idempotency keys, and error responses. Provides verification code, dedupe storage strategy, runbook for incidents. Use when implementing "webhooks", "webhook security", "event receivers", or "third-party integrations".
+---
+
+# Webhook Receiver Hardener
+
+Build secure, reliable webhook endpoints that handle failures gracefully.
+
+## Core Security
+
+**Signature Verification**: HMAC validation before processing
+**Deduplication**: Track processed webhook IDs
+**Idempotency**: Safe to process same webhook multiple times
+**Retries**: Handle provider retry attempts
+**Rate Limiting**: Prevent abuse
+
+## Signature Verification
+
+```typescript
+import crypto from "crypto";
+
+export const verifyWebhookSignature = (
+  payload: string,
+  signature: string,
+  secret: string
+): boolean => {
+  const hmac = crypto
+    .createHmac("sha256", secret)
+    .update(payload)
+    .digest("hex");
+
+  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(hmac));
+};
+
+// Stripe example
+router.post(
+  "/webhooks/stripe",
+  express.raw({ type: "application/json" }),
+  async (req, res) => {
+    const sig = req.headers["stripe-signature"];
+
+    try {
+      const event = stripe.webhooks.constructEvent(
+        req.body,
+        sig,
+        process.env.STRIPE_WEBHOOK_SECRET
+      );
+      await processStripeEvent(event);
+      res.json({ received: true });
+    } catch (err) {
+      return res.status(400).send(`Webhook Error: ${err.message}`);
+    }
+  }
+);
+```
+
+## Deduplication
+
+```typescript
+// Redis-based dedupe
+const WEBHOOK_TTL = 60 * 60 * 24; // 24 hours
+
+export const isDuplicate = async (webhookId: string): Promise<boolean> => {
+  const key = `webhook:${webhookId}`;
+  const exists = await redis.exists(key);
+
+  if (exists) return true;
+
+  await redis.setex(key, WEBHOOK_TTL, "1");
+  return false;
+};
+
+// Usage
+if (await isDuplicate(webhook.id)) {
+  return res.status(200).json({ received: true }); // Already processed
+}
+```
+
+## Idempotent Processing
+
+```typescript
+export const processWebhook = async (webhook: Webhook) => {
+  // Use database transaction with unique constraint
+  try {
+    await db.transaction(async (trx) => {
+      // Insert webhook record (unique constraint on webhook_id)
+      await trx("processed_webhooks").insert({
+        webhook_id: webhook.id,
+        processed_at: new Date(),
+      });
+
+      // Do actual processing
+      await performWebhookAction(webhook, trx);
+    });
+  } catch (err) {
+    if (err.code === "23505") {
+      // Unique violation
+      console.log("Webhook already processed");
+      return; // Idempotent - already processed
+    }
+    throw err;
+  }
+};
+```
+
+## Retry Handling
+
+```typescript
+// Acknowledge immediately, process async
+router.post("/webhooks/provider", async (req, res) => {
+  // Verify signature
+  if (!verifySignature(req.body, req.headers["signature"])) {
+    return res.status(401).send("Invalid signature");
+  }
+
+  // Return 200 immediately
+  res.status(200).json({ received: true });
+
+  // Process async
+  processWebhookAsync(req.body).catch((err) => {
+    console.error("Webhook processing failed:", err);
+    // Will be retried by provider
+  });
+});
+
+// Exponential backoff for provider retries
+// Attempt 1: immediate
+// Attempt 2: +5 minutes
+// Attempt 3: +15 minutes
+// Attempt 4: +1 hour
+// Attempt 5: +6 hours
+```
+
+## Error Responses
+
+```typescript
+// Return appropriate status codes
+const webhookHandler = async (req, res) => {
+  // 400: Malformed payload (won't retry)
+  if (!isValidPayload(req.body)) {
+    return res.status(400).json({ error: "Invalid payload" });
+  }
+
+  // 401: Invalid signature (won't retry)
+  if (!verifySignature(req.body, req.headers["signature"])) {
+    return res.status(401).json({ error: "Invalid signature" });
+  }
+
+  // 200: Already processed (idempotent)
+  if (await isDuplicate(req.body.id)) {
+    return res.status(200).json({ received: true });
+  }
+
+  // 500: Processing error (will retry)
+  try {
+    await processWebhook(req.body);
+    return res.status(200).json({ received: true });
+  } catch (err) {
+    console.error("Processing error:", err);
+    return res.status(500).json({ error: "Processing failed" });
+  }
+};
+```
+
+## Monitoring & Runbook
+
+```markdown
+## Webhook Incidents
+
+### High Error Rate
+
+1. Check provider status page
+2. Review recent code deploys
+3. Check signature secret rotation
+4. Verify database connectivity
+
+### Missing Webhooks
+
+1. Check provider sending (their dashboard)
+2. Verify endpoint is accessible
+3. Check rate limiting rules
+4. Review dedupe cache TTL
+
+### Duplicate Processing
+
+1. Check dedupe cache connectivity
+2. Verify unique constraints
+3. Review idempotency logic
+```
+
+## Best Practices
+
+- Verify signature BEFORE any processing
+- Return 200 quickly, process async
+- Dedupe with Redis + database constraints
+- Log all webhook attempts
+- Monitor processing latency
+- Set up alerts for failures
+- Document expected payload schemas
+
+## Output Checklist
+
+- [ ] Signature verification
+- [ ] Deduplication mechanism
+- [ ] Idempotent processing
+- [ ] Async processing pattern
+- [ ] Proper status codes
+- [ ] Error logging
+- [ ] Monitoring/alerts
+- [ ] Incident runbook

package/templates/ci-cd/artifact-sbom-publisher/ SKILL.md

@@ -0,0 +1,236 @@
+---
+name: artifact-sbom-publisher
+description: Produces build artifacts with Software Bill of Materials (SBOM) and supply chain metadata for security and compliance. Use for "artifact publishing", "SBOM generation", "supply chain security", or "build provenance".
+---
+
+# Artifact & SBOM Publisher
+
+Generate and publish artifacts with supply chain security metadata.
+
+## Build Artifacts
+
+```yaml
+build:
+  runs-on: ubuntu-latest
+  steps:
+    - uses: actions/checkout@v4
+
+    - uses: actions/setup-node@v4
+      with:
+        node-version: "20"
+
+    - run: npm ci
+    - run: npm run build
+
+    - name: Upload artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: dist-${{ github.sha }}
+        path: |
+          dist/
+          !dist/**/*.map
+        retention-days: 30
+        if-no-files-found: error
+```
+
+## SBOM Generation (CycloneDX)
+
+```yaml
+sbom:
+  runs-on: ubuntu-latest
+  steps:
+    - uses: actions/checkout@v4
+
+    - name: Generate SBOM
+      uses: CycloneDX/gh-node-module-generatebom@master
+      with:
+        path: ./
+        output: ./sbom.json
+
+    - name: Upload SBOM
+      uses: actions/upload-artifact@v4
+      with:
+        name: sbom-${{ github.sha }}
+        path: sbom.json
+```
+
+## SBOM with Syft
+
+```yaml
+- name: Generate SBOM with Syft
+  run: |
+    curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b /usr/local/bin
+    syft . -o spdx-json > sbom-spdx.json
+    syft . -o cyclonedx-json > sbom-cyclonedx.json
+
+- name: Upload SBOMs
+  uses: actions/upload-artifact@v4
+  with:
+    name: sboms
+    path: |
+      sbom-spdx.json
+      sbom-cyclonedx.json
+```
+
+## Docker Image SBOM
+
+```yaml
+- name: Build image
+  uses: docker/build-push-action@v5
+  with:
+    context: .
+    push: true
+    tags: myapp:${{ github.sha }}
+    sbom: true
+    provenance: true
+
+- name: Generate SBOM for image
+  run: |
+    syft myapp:${{ github.sha }} -o spdx-json > image-sbom.json
+
+- name: Scan SBOM for vulnerabilities
+  uses: anchore/scan-action@v3
+  with:
+    sbom: image-sbom.json
+    fail-build: true
+    severity-cutoff: high
+```
+
+## Build Provenance (SLSA)
+
+```yaml
+provenance:
+  runs-on: ubuntu-latest
+  permissions:
+    actions: read
+    id-token: write
+    contents: write
+  steps:
+    - uses: actions/checkout@v4
+
+    - name: Build
+      run: npm run build
+
+    - name: Generate provenance
+      uses: actions/attest-build-provenance@v1
+      with:
+        subject-path: "dist/**"
+```
+
+## Artifact Metadata
+
+```yaml
+- name: Create artifact metadata
+  run: |
+    cat > artifact-metadata.json << EOF
+    {
+      "version": "${{ github.ref_name }}",
+      "commit": "${{ github.sha }}",
+      "branch": "${{ github.ref }}",
+      "build_time": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+      "builder": "GitHub Actions",
+      "workflow": "${{ github.workflow }}",
+      "run_id": "${{ github.run_id }}",
+      "actor": "${{ github.actor }}"
+    }
+    EOF
+
+- name: Upload metadata
+  uses: actions/upload-artifact@v4
+  with:
+    name: metadata
+    path: artifact-metadata.json
+```
+
+## Package & Release
+
+```yaml
+release:
+  runs-on: ubuntu-latest
+  needs: [build, sbom]
+  if: github.event_name == 'release'
+  steps:
+    - name: Download artifacts
+      uses: actions/download-artifact@v4
+      with:
+        path: artifacts/
+
+    - name: Create release package
+      run: |
+        cd artifacts
+        tar -czf ../release.tar.gz dist-* sbom-* metadata/
+
+    - name: Upload to release
+      uses: actions/upload-release-asset@v1
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      with:
+        upload_url: ${{ github.event.release.upload_url }}
+        asset_path: ./release.tar.gz
+        asset_name: release-${{ github.ref_name }}.tar.gz
+        asset_content_type: application/gzip
+```
+
+## Vulnerability Scanning
+
+```yaml
+- name: Scan SBOM for vulnerabilities
+  uses: aquasecurity/trivy-action@master
+  with:
+    scan-type: "sbom"
+    format: "sarif"
+    output: "trivy-results.sarif"
+    sbom-sources: "sbom.json"
+
+- name: Upload scan results
+  uses: github/codeql-action/upload-sarif@v3
+  with:
+    sarif_file: "trivy-results.sarif"
+```
+
+## Artifact Attestation
+
+```yaml
+- name: Attest artifact
+  uses: actions/attest@v1
+  with:
+    subject-path: "dist/myapp.tar.gz"
+    predicate-type: "https://slsa.dev/provenance/v1"
+    predicate: |
+      {
+        "buildType": "https://github.com/actions/workflow",
+        "builder": {
+          "id": "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+        },
+        "metadata": {
+          "buildInvocationId": "${{ github.run_id }}",
+          "completeness": {
+            "parameters": true,
+            "environment": false,
+            "materials": true
+          }
+        }
+      }
+```
+
+## Best Practices
+
+1. **Generate SBOMs**: For all releases
+2. **Multiple formats**: SPDX and CycloneDX
+3. **Scan vulnerabilities**: Before release
+4. **Sign artifacts**: For verification
+5. **Include provenance**: SLSA attestation
+6. **Retention policy**: Keep artifacts 30 days
+7. **Metadata**: Version, commit, timestamp
+8. **Automate**: Part of every build
+
+## Output Checklist
+
+- [ ] Build artifacts uploaded
+- [ ] SBOM generated (SPDX or CycloneDX)
+- [ ] Vulnerability scanning configured
+- [ ] Build provenance generated
+- [ ] Artifact metadata included
+- [ ] Release packaging automated
+- [ ] Attestation/signing (optional)
+- [ ] Retention policy set