javi-forge 1.1.0 → 1.3.0

package/ai-config/skills/backend/jwt-auth/SKILL.md

@@ -1,412 +0,0 @@
----
-name: jwt-auth
-description: >
-  JWT authentication with access/refresh tokens, RBAC, and multi-tenant support.
-  Trigger: jwt, authentication, auth, token, rbac, authorization, login
-tools:
-  - Read
-  - Write
-  - Bash
-  - Grep
-metadata:
-  author: plataforma-industrial
-  version: "2.0"
-  tags: [security, jwt, auth, rbac]
-  updated: "2026-02"
----
-
-# JWT Authentication Skill
-
-## Stack
-
-```yaml
-# Go
-golang-jwt/jwt: v5
-bcrypt: golang.org/x/crypto/bcrypt
-
-# TypeScript
-jose: 5.2+
-
-# Python
-PyJWT: 2.8+
-passlib: 1.7+
-```
-
-## Token Structure
-
-### Claims
-
-```json
-{
-  "iss": "app-name",
-  "sub": "user-123",
-  "aud": ["api"],
-  "exp": 1704067200,
-  "iat": 1704063600,
-  "uid": "user-123",
-  "tid": "tenant-456",
-  "role": "operator",
-  "scopes": ["items:read", "items:write", "alerts:read"]
-}
-```
-
-## Go Implementation
-
-### JWT Service
-
-```go
-// auth/jwt.go
-package auth
-
-import (
-    "time"
-    "github.com/golang-jwt/jwt/v5"
-)
-
-type AccessTokenClaims struct {
-    jwt.RegisteredClaims
-    UserID   string   `json:"uid"`
-    TenantID string   `json:"tid"`
-    Role     string   `json:"role"`
-    Scopes   []string `json:"scopes,omitempty"`
-}
-
-type JWTConfig struct {
-    AccessSecret    []byte
-    RefreshSecret   []byte
-    AccessDuration  time.Duration  // 15 minutes
-    RefreshDuration time.Duration  // 7 days
-    Issuer          string
-}
-
-type JWTService struct {
-    config JWTConfig
-}
-
-func (s *JWTService) GenerateAccessToken(user *User) (string, error) {
-    now := time.Now()
-    claims := AccessTokenClaims{
-        RegisteredClaims: jwt.RegisteredClaims{
-            Issuer:    s.config.Issuer,
-            Subject:   user.ID,
-            ExpiresAt: jwt.NewNumericDate(now.Add(s.config.AccessDuration)),
-            IssuedAt:  jwt.NewNumericDate(now),
-        },
-        UserID:   user.ID,
-        TenantID: user.TenantID,
-        Role:     user.Role,
-        Scopes:   user.Scopes,
-    }
-    token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
-    return token.SignedString(s.config.AccessSecret)
-}
-
-func (s *JWTService) ValidateAccessToken(tokenString string) (*AccessTokenClaims, error) {
-    token, err := jwt.ParseWithClaims(
-        tokenString,
-        &AccessTokenClaims{},
-        func(token *jwt.Token) (interface{}, error) {
-            if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
-                return nil, ErrInvalidToken
-            }
-            return s.config.AccessSecret, nil
-        },
-    )
-    if err != nil {
-        return nil, ErrInvalidToken
-    }
-    claims, ok := token.Claims.(*AccessTokenClaims)
-    if !ok || !token.Valid {
-        return nil, ErrInvalidClaims
-    }
-    return claims, nil
-}
-```
-
-### Auth Middleware
-
-```go
-// middleware/auth.go
-type contextKey string
-
-const (
-    UserIDKey   contextKey = "user_id"
-    TenantIDKey contextKey = "tenant_id"
-    RoleKey     contextKey = "role"
-    ScopesKey   contextKey = "scopes"
-)
-
-func (m *AuthMiddleware) Authenticate(next http.Handler) http.Handler {
-    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-        authHeader := r.Header.Get("Authorization")
-        if !strings.HasPrefix(authHeader, "Bearer ") {
-            http.Error(w, "Unauthorized", http.StatusUnauthorized)
-            return
-        }
-
-        claims, err := m.jwtService.ValidateAccessToken(authHeader[7:])
-        if err != nil {
-            http.Error(w, "Invalid token", http.StatusUnauthorized)
-            return
-        }
-
-        ctx := r.Context()
-        ctx = context.WithValue(ctx, UserIDKey, claims.UserID)
-        ctx = context.WithValue(ctx, TenantIDKey, claims.TenantID)
-        ctx = context.WithValue(ctx, RoleKey, claims.Role)
-        ctx = context.WithValue(ctx, ScopesKey, claims.Scopes)
-
-        next.ServeHTTP(w, r.WithContext(ctx))
-    })
-}
-
-func (m *AuthMiddleware) RequireRole(roles ...string) func(http.Handler) http.Handler {
-    return func(next http.Handler) http.Handler {
-        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-            role := r.Context().Value(RoleKey).(string)
-            for _, allowed := range roles {
-                if role == allowed {
-                    next.ServeHTTP(w, r)
-                    return
-                }
-            }
-            http.Error(w, "Forbidden", http.StatusForbidden)
-        })
-    }
-}
-
-func (m *AuthMiddleware) RequireScope(required string) func(http.Handler) http.Handler {
-    return func(next http.Handler) http.Handler {
-        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-            scopes := r.Context().Value(ScopesKey).([]string)
-            for _, scope := range scopes {
-                if scope == required || scope == "*" {
-                    next.ServeHTTP(w, r)
-                    return
-                }
-            }
-            http.Error(w, "Insufficient permissions", http.StatusForbidden)
-        })
-    }
-}
-
-// Helpers
-func GetUserID(ctx context.Context) string {
-    if v := ctx.Value(UserIDKey); v != nil {
-        return v.(string)
-    }
-    return ""
-}
-
-func GetTenantID(ctx context.Context) string {
-    if v := ctx.Value(TenantIDKey); v != nil {
-        return v.(string)
-    }
-    return ""
-}
-```
-
-### Login Handler
-
-```go
-type TokenResponse struct {
-    AccessToken  string `json:"access_token"`
-    RefreshToken string `json:"refresh_token"`
-    ExpiresIn    int    `json:"expires_in"`
-    TokenType    string `json:"token_type"`
-}
-
-func (h *Handler) handleLogin(w http.ResponseWriter, r *http.Request) {
-    var req LoginRequest
-    json.NewDecoder(r.Body).Decode(&req)
-
-    user, _ := h.userRepo.GetByEmail(r.Context(), req.Email)
-
-    if err := bcrypt.CompareHashAndPassword(
-        []byte(user.PasswordHash), []byte(req.Password),
-    ); err != nil {
-        respondError(w, http.StatusUnauthorized, "Invalid credentials")
-        return
-    }
-
-    accessToken, _ := h.jwtService.GenerateAccessToken(user)
-    refreshToken, tokenID, _ := h.jwtService.GenerateRefreshToken(user)
-
-    h.tokenStore.Store(r.Context(), tokenID, user.ID, 7*24*time.Hour)
-
-    respondJSON(w, http.StatusOK, TokenResponse{
-        AccessToken:  accessToken,
-        RefreshToken: refreshToken,
-        ExpiresIn:    900,
-        TokenType:    "Bearer",
-    })
-}
-```
-
-## TypeScript Client
-
-### Auth Store (Zustand)
-
-```typescript
-import { create } from 'zustand';
-import { persist } from 'zustand/middleware';
-import { jwtDecode } from 'jwt-decode';
-
-interface TokenPayload {
-  uid: string;
-  tid: string;
-  role: string;
-  scopes: string[];
-  exp: number;
-}
-
-interface AuthState {
-  accessToken: string | null;
-  refreshToken: string | null;
-  user: TokenPayload | null;
-  isAuthenticated: boolean;
-  setTokens: (access: string, refresh: string) => void;
-  logout: () => void;
-  isTokenExpired: () => boolean;
-  hasScope: (scope: string) => boolean;
-  hasRole: (role: string) => boolean;
-}
-
-export const useAuthStore = create<AuthState>()(
-  persist(
-    (set, get) => ({
-      accessToken: null,
-      refreshToken: null,
-      user: null,
-      isAuthenticated: false,
-
-      setTokens: (accessToken, refreshToken) => {
-        const payload = jwtDecode<TokenPayload>(accessToken);
-        set({ accessToken, refreshToken, user: payload, isAuthenticated: true });
-      },
-
-      logout: () => set({
-        accessToken: null, refreshToken: null, user: null, isAuthenticated: false
-      }),
-
-      isTokenExpired: () => {
-        const { user } = get();
-        return !user || Date.now() >= user.exp * 1000;
-      },
-
-      hasScope: (scope) => {
-        const { user } = get();
-        return user?.scopes.includes(scope) || user?.scopes.includes('*') || false;
-      },
-
-      hasRole: (role) => get().user?.role === role,
-    }),
-    { name: 'auth-storage' }
-  )
-);
-```
-
-### API Client with Auto-Refresh
-
-```typescript
-class ApiClient {
-  private refreshPromise: Promise<void> | null = null;
-
-  async fetch<T>(path: string, options: RequestInit = {}): Promise<T> {
-    const { accessToken, isTokenExpired } = useAuthStore.getState();
-
-    if (accessToken && isTokenExpired()) {
-      await this.refreshToken();
-    }
-
-    const response = await this.makeRequest(path, options);
-
-    if (response.status === 401) {
-      await this.refreshToken();
-      return this.makeRequest(path, options).then(r => r.json());
-    }
-
-    return response.json();
-  }
-
-  private async refreshToken(): Promise<void> {
-    if (this.refreshPromise) return this.refreshPromise;
-
-    const { refreshToken, setTokens, logout } = useAuthStore.getState();
-    if (!refreshToken) { logout(); throw new Error('No refresh token'); }
-
-    this.refreshPromise = (async () => {
-      try {
-        const response = await fetch(`${API_URL}/auth/refresh`, {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ refresh_token: refreshToken }),
-        });
-        if (!response.ok) { logout(); throw new Error('Refresh failed'); }
-        const data = await response.json();
-        setTokens(data.access_token, data.refresh_token);
-      } finally {
-        this.refreshPromise = null;
-      }
-    })();
-
-    return this.refreshPromise;
-  }
-}
-```
-
-### Protected Route (React)
-
-```tsx
-function ProtectedRoute({ children, requiredRole, requiredScope }: Props) {
-  const { isAuthenticated, hasRole, hasScope } = useAuthStore();
-
-  if (!isAuthenticated) return <Navigate to="/login" />;
-  if (requiredRole && !hasRole(requiredRole)) return <Navigate to="/unauthorized" />;
-  if (requiredScope && !hasScope(requiredScope)) return <Navigate to="/unauthorized" />;
-
-  return <>{children}</>;
-}
-```
-
-## Database Schema
-
-```sql
-CREATE TABLE roles (
-    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    name TEXT NOT NULL UNIQUE,
-    scopes TEXT[] NOT NULL DEFAULT '{}'
-);
-
-INSERT INTO roles (name, scopes) VALUES
-('viewer', ARRAY['items:read', 'dashboard:read']),
-('operator', ARRAY['items:read', 'items:write', 'alerts:acknowledge']),
-('admin', ARRAY['*']);
-
-CREATE TABLE users (
-    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    tenant_id UUID NOT NULL REFERENCES tenants(id),
-    email TEXT NOT NULL,
-    password_hash TEXT NOT NULL,
-    role_id UUID NOT NULL REFERENCES roles(id),
-    active BOOLEAN DEFAULT true,
-    UNIQUE(tenant_id, email)
-);
-```
-
-## Security Best Practices
-
-1. **Short access tokens**: 15 minutes max
-2. **Longer refresh tokens**: 7 days for UX
-3. **Token revocation**: Store refresh token IDs in Redis
-4. **Rate limit auth endpoints**: 5 attempts/minute
-5. **Password hashing**: bcrypt with cost >= 12
-6. **Secure storage**: HttpOnly cookies for refresh, memory for access
-7. **Rotate on refresh**: Issue new refresh token on each use
-
-## Related Skills
-
-- `fastapi`: Python auth integration
-- `chi-router`: Go auth middleware
-- `redis-cache`: Token blacklist storage
-- `zod-validation`: Token payload validation

package/ai-config/skills/backend/notifications-concepts/SKILL.md

@@ -1,259 +0,0 @@
----
-name: notifications-concepts
-description: >
-  Notification system concepts. Email, SMS, Push, in-app notifications, delivery tracking.
-  Trigger: notifications, email, SMS, push, FCM, APNS, in-app
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-metadata:
-  author: apigen-team
-  version: "1.0"
-  tags: [notifications, email, sms, push]
-  scope: ["**/notifications/**"]
----
-
-# Notification System Concepts
-
-## Notification Channels
-
-### Email
-```
-Providers:
-- SendGrid, Mailgun, AWS SES, Postmark
-
-Use cases:
-- Transactional (receipts, password reset)
-- Marketing (newsletters, promotions)
-- System alerts (security, billing)
-
-Considerations:
-- Deliverability (SPF, DKIM, DMARC)
-- Bounce handling
-- Unsubscribe management
-- Template rendering
-```
-
-### SMS
-```
-Providers:
-- Twilio, Vonage, AWS SNS, MessageBird
-
-Use cases:
-- 2FA/OTP codes
-- Order updates
-- Appointment reminders
-- Emergency alerts
-
-Considerations:
-- Character limits (160 GSM-7, 70 Unicode)
-- Delivery receipts
-- Opt-in/opt-out (TCPA compliance)
-- Cost per message
-```
-
-### Push Notifications
-```
-Platforms:
-- FCM (Firebase Cloud Messaging) - Android/Web
-- APNS (Apple Push Notification Service) - iOS
-- Web Push (PWA)
-
-Use cases:
-- Real-time updates
-- Re-engagement
-- Breaking news
-- Chat messages
-
-Considerations:
-- Device token management
-- Silent vs visible notifications
-- Badge counts
-- Action buttons
-```
-
-### In-App Notifications
-```
-Types:
-- Toast/snackbar (transient)
-- Banner (persistent until dismissed)
-- Badge (counter on icon)
-- Feed (notification center)
-
-Use cases:
-- Feature announcements
-- Activity updates
-- Social interactions
-- System messages
-```
-
-## Notification Architecture
-
-```
-┌──────────────┐
-│ Application  │
-└──────┬───────┘
-       ↓
-┌──────────────────────────────────┐
-│     Notification Service         │
-│  ┌────────────────────────────┐  │
-│  │   Channel Router           │  │
-│  └────────────────────────────┘  │
-│       ↓         ↓         ↓      │
-│  ┌────────┐ ┌────────┐ ┌────────┐│
-│  │ Email  │ │  SMS   │ │  Push  ││
-│  │Provider│ │Provider│ │Provider││
-│  └────────┘ └────────┘ └────────┘│
-└──────────────────────────────────┘
-       ↓         ↓         ↓
-   Mailgun    Twilio      FCM
-```
-
-## Notification Data Model
-
-```
-Notification:
-  id: UUID
-  userId: string
-  type: enum (transactional, marketing, system)
-  channel: enum (email, sms, push, in_app)
-  template: string
-  data: JSON (template variables)
-  status: enum (pending, sent, delivered, failed, read)
-  scheduledAt: timestamp (null = immediate)
-  sentAt: timestamp
-  deliveredAt: timestamp
-  readAt: timestamp
-  metadata: JSON
-
-Template:
-  id: string
-  channel: enum
-  subject: string (email only)
-  body: string (with placeholders)
-  locale: string
-```
-
-## User Preferences
-
-```json
-{
-  "userId": "user-123",
-  "channels": {
-    "email": {
-      "enabled": true,
-      "address": "user@example.com",
-      "verified": true
-    },
-    "sms": {
-      "enabled": true,
-      "number": "+1234567890",
-      "verified": true
-    },
-    "push": {
-      "enabled": true,
-      "tokens": [
-        {"platform": "ios", "token": "xxx"},
-        {"platform": "android", "token": "yyy"}
-      ]
-    }
-  },
-  "preferences": {
-    "marketing": false,
-    "orderUpdates": true,
-    "securityAlerts": true,
-    "quietHours": {
-      "enabled": true,
-      "start": "22:00",
-      "end": "08:00",
-      "timezone": "America/New_York"
-    }
-  }
-}
-```
-
-## Delivery Strategies
-
-### Priority-based Routing
-```
-Critical (security alerts):
-  1. Push (immediate)
-  2. SMS (fallback)
-  3. Email (always)
-
-Transactional (order updates):
-  1. Push if available
-  2. Email always
-
-Marketing:
-  1. Email only
-  2. Respect preferences
-```
-
-### Batching
-```
-Individual: Send immediately
-  - Password reset
-  - OTP codes
-
-Batched: Aggregate and send
-  - Social notifications ("5 people liked your post")
-  - Activity digests
-
-Scheduled: Send at optimal time
-  - Marketing campaigns
-  - Weekly summaries
-```
-
-## Tracking & Analytics
-
-```
-Metrics to track:
-- Send rate (attempted)
-- Delivery rate (confirmed)
-- Open rate (email/push)
-- Click rate (links)
-- Bounce rate (email)
-- Unsubscribe rate
-- Opt-out rate
-
-Events:
-- notification.created
-- notification.sent
-- notification.delivered
-- notification.opened
-- notification.clicked
-- notification.bounced
-- notification.failed
-```
-
-## Best Practices
-
-```
-Content:
-✅ Clear, actionable subject lines
-✅ Personalization (name, context)
-✅ Mobile-friendly formatting
-✅ Unsubscribe link (email)
-❌ Misleading subjects
-❌ Excessive frequency
-❌ Sending without consent
-
-Technical:
-✅ Idempotent sending
-✅ Retry with backoff
-✅ Rate limiting per user
-✅ Template versioning
-❌ Hardcoded content
-❌ Synchronous sending
-❌ Ignoring bounces
-```
-
-## Related Skills
-
-- `notifications-spring`: Spring Boot notification implementation
-- `apigen-architecture`: Overall system architecture
-
-