@planu/cli 0.96.5 → 0.97.0

package/src/config/spec-templates/email-notifications/spec.md

@@ -0,0 +1,31 @@
+# Email Notifications — {{provider}}
+
+## Overview
+Transactional email system using {{provider}} sent from `{{from_address}}`, with template rendering, {{queue_enabled}} async queuing, and delivery tracking.
+
+## Acceptance Criteria
+
+### AC-1: Template Rendering
+- Define email templates with subject and HTML/text body variants
+- Interpolate dynamic variables (e.g. `{{user_name}}`, `{{action_url}}`) at send time
+- Validate all required variables are provided before queuing
+
+### AC-2: Sending via {{provider}}
+- Send emails via {{provider}} API using environment-configured credentials
+- Set `From: {{from_address}}` on all outgoing emails
+- Handle API errors with retry logic (3 attempts, exponential backoff)
+
+### AC-3: Async Queue
+- When `queue_enabled` is {{queue_enabled}}, enqueue emails instead of sending synchronously
+- Worker processes the queue and marks emails as `sent` or `failed`
+- Retry failed sends up to 3 times before marking as permanently failed
+
+### AC-4: Delivery Tracking
+- Store delivery records: recipient, template, status, sentAt, provider message ID
+- Expose delivery status via an internal admin API
+- Alert when failure rate exceeds 5% in a 1-hour window
+
+## Technical Notes
+- Never log email body content — only metadata (recipient, template name, status)
+- Implement unsubscribe links and honor opt-out preferences
+- Test with {{provider}} sandbox/test mode before production deployment

package/src/config/spec-templates/email-notifications/template.json

@@ -0,0 +1,10 @@
+{
+  "name": "email-notifications",
+  "description": "Transactional email system with templates, queuing, and delivery tracking",
+  "variables": [
+    { "name": "provider", "description": "Email provider (sendgrid, mailgun, ses, resend)", "default": "sendgrid" },
+    { "name": "from_address", "description": "Default sender email address", "default": "noreply@example.com" },
+    { "name": "queue_enabled", "description": "Whether to queue emails asynchronously (true/false)", "default": "true" }
+  ],
+  "tags": ["email", "notifications", "backend", "queuing"]
+}

package/src/config/spec-templates/file-upload-s3/spec.md

@@ -0,0 +1,31 @@
+# File Upload — {{provider}}
+
+## Overview
+Secure file upload system using {{provider}} bucket `{{bucket_name}}` with presigned URLs, a maximum file size of {{max_size_mb}} MB, and allowed types: {{allowed_types}}.
+
+## Acceptance Criteria
+
+### AC-1: Presigned URL Generation
+- Generate a presigned upload URL valid for 15 minutes
+- URL is scoped to the authenticated user's namespace
+- Enforce `Content-Type` matching one of: {{allowed_types}}
+
+### AC-2: File Validation
+- Reject uploads exceeding {{max_size_mb}} MB with a clear error
+- Validate MIME type against the Content-Type header
+- Scan file content for malicious patterns before confirming upload
+
+### AC-3: Upload Confirmation
+- Client calls confirm endpoint after direct upload to {{provider}}
+- Server verifies the object exists in `{{bucket_name}}` before saving metadata
+- Store file metadata (name, size, type, owner, uploadedAt) in the database
+
+### AC-4: Download and Deletion
+- Generate presigned download URLs valid for 1 hour
+- Delete the object from `{{bucket_name}}` and metadata on user request
+- Restrict access so users can only download/delete their own files
+
+## Technical Notes
+- Never expose {{provider}} credentials to the client
+- Use server-side encryption at rest in `{{bucket_name}}`
+- Log all upload attempts (success and failure) with user ID and file metadata

package/src/config/spec-templates/file-upload-s3/template.json

@@ -0,0 +1,11 @@
+{
+  "name": "file-upload-s3",
+  "description": "File upload system with cloud storage, presigned URLs, and file validation",
+  "variables": [
+    { "name": "provider", "description": "Cloud storage provider (s3, gcs, r2)", "default": "s3" },
+    { "name": "bucket_name", "description": "Name of the storage bucket", "default": "uploads" },
+    { "name": "max_size_mb", "description": "Maximum allowed file size in megabytes", "default": "10" },
+    { "name": "allowed_types", "description": "Comma-separated list of allowed MIME types", "default": "image/jpeg,image/png,application/pdf" }
+  ],
+  "tags": ["file-upload", "s3", "storage", "backend"]
+}

package/src/config/spec-templates/jwt-auth/spec.md

@@ -0,0 +1,35 @@
+# JWT Authentication
+
+## Overview
+JWT-based authentication with {{algorithm}} signing, access tokens valid for {{access_token_ttl}}, refresh tokens valid for {{refresh_token_ttl}}, and token rotation on refresh.
+
+## Acceptance Criteria
+
+### AC-1: Login
+- Accept `email` and `password` credentials
+- Issue a signed access token ({{algorithm}}, TTL {{access_token_ttl}}) and refresh token (TTL {{refresh_token_ttl}})
+- Return tokens in the response body; set refresh token as `HttpOnly` cookie
+
+### AC-2: Token Verification
+- Validate signature, expiry, and issuer on every protected route
+- Return 401 with a clear message when token is expired or invalid
+- Extract user claims (id, role, email) from token without a database lookup
+
+### AC-3: Token Refresh
+- Accept refresh token from `HttpOnly` cookie
+- Issue new access and refresh tokens (rotation)
+- Blacklist the previous refresh token to prevent reuse
+
+### AC-4: Logout
+- Blacklist the current refresh token on logout
+- Clear the `HttpOnly` cookie
+- Return 204 on success
+
+### AC-5: Token Blacklist
+- Store blacklisted token JTIs in a fast store (Redis recommended)
+- Entries expire automatically at token TTL to prevent unbounded growth
+
+## Technical Notes
+- Never store the raw JWT secret in application code — use environment variables
+- Include `jti` (JWT ID) claim for blacklist lookups
+- Rotate signing keys on a quarterly schedule

package/src/config/spec-templates/jwt-auth/template.json

@@ -0,0 +1,10 @@
+{
+  "name": "jwt-auth",
+  "description": "JWT authentication with access/refresh token rotation, blacklisting, and role-based claims",
+  "variables": [
+    { "name": "access_token_ttl", "description": "Access token time-to-live (e.g. 15m, 1h)", "default": "15m" },
+    { "name": "refresh_token_ttl", "description": "Refresh token time-to-live (e.g. 7d, 30d)", "default": "7d" },
+    { "name": "algorithm", "description": "JWT signing algorithm (HS256, RS256)", "default": "HS256" }
+  ],
+  "tags": ["auth", "jwt", "security", "backend"]
+}

package/src/config/spec-templates/oauth-social-login/spec.md

@@ -0,0 +1,31 @@
+# OAuth2 Social Login — {{provider}}
+
+## Overview
+Implement OAuth2 social login via {{provider}} with secure token handling and session management lasting {{session_duration}} seconds.
+
+## Acceptance Criteria
+
+### AC-1: OAuth Authorization Flow
+- Redirect users to {{provider}} authorization endpoint with correct scopes
+- Handle the callback at {{callback_path}} and exchange code for tokens
+- Validate the `state` parameter to prevent CSRF attacks
+
+### AC-2: User Account Linking
+- Create a new user account if the OAuth identity does not exist
+- Link the OAuth identity to an existing account if the email matches
+- Store the provider, provider user ID, and access token securely
+
+### AC-3: Session Management
+- Issue a signed session token valid for {{session_duration}} seconds after successful login
+- Invalidate session on explicit logout
+- Refresh session silently when less than 10% of lifetime remains
+
+### AC-4: Error Handling
+- Return clear errors when the user denies authorization
+- Handle provider API outages with a user-friendly fallback message
+- Log all authentication failures with anonymized user identifiers
+
+## Technical Notes
+- Never store OAuth access tokens in client-accessible cookies
+- Use PKCE (Proof Key for Code Exchange) when supported by the provider
+- Implement rate limiting on the callback endpoint to prevent abuse

package/src/config/spec-templates/oauth-social-login/template.json

@@ -0,0 +1,10 @@
+{
+  "name": "oauth-social-login",
+  "description": "OAuth2 social login with Google and GitHub, including token handling and session management",
+  "variables": [
+    { "name": "provider", "description": "OAuth provider to integrate (google, github, or both)", "default": "google" },
+    { "name": "callback_path", "description": "OAuth callback URL path", "default": "/auth/callback" },
+    { "name": "session_duration", "description": "Session duration in seconds", "default": "86400" }
+  ],
+  "tags": ["auth", "oauth2", "social-login", "google", "github", "backend"]
+}

package/src/config/spec-templates/rate-limiting/spec.md

@@ -0,0 +1,31 @@
+# Rate Limiting Middleware
+
+## Overview
+Sliding window rate limiting middleware with a limit of {{requests_per_window}} requests per {{window_seconds}} seconds, applied per {{strategy}}.
+
+## Acceptance Criteria
+
+### AC-1: Sliding Window Enforcement
+- Track request counts in a {{window_seconds}}-second sliding window per {{strategy}}
+- Block requests exceeding {{requests_per_window}} with HTTP 429
+- Include `Retry-After` header indicating seconds until the window resets
+
+### AC-2: Response Headers
+- Include `X-RateLimit-Limit: {{requests_per_window}}` on all responses
+- Include `X-RateLimit-Remaining` with current remaining count
+- Include `X-RateLimit-Reset` with the Unix timestamp of window expiry
+
+### AC-3: Strategy Configuration
+- Apply limits by {{strategy}} (ip address, authenticated user ID, or API key)
+- Fall back to IP-based limiting for unauthenticated requests
+- Support per-route override limits via middleware options
+
+### AC-4: Bypass and Exemptions
+- Allow exemption list for internal service IPs
+- Support admin-level bypass via a trusted header `X-Internal-Request: true`
+- Log all exemptions for audit purposes
+
+## Technical Notes
+- Use atomic Redis operations (INCR + EXPIRE) to avoid race conditions
+- Store counters in Redis with TTL equal to the window duration
+- Degrade gracefully to allow-all if Redis is unavailable (fail open with alert)

package/src/config/spec-templates/rate-limiting/template.json

@@ -0,0 +1,10 @@
+{
+  "name": "rate-limiting",
+  "description": "Rate limiting middleware with sliding window algorithm, per-user and per-IP limits",
+  "variables": [
+    { "name": "requests_per_window", "description": "Maximum requests allowed per window", "default": "100" },
+    { "name": "window_seconds", "description": "Time window in seconds", "default": "60" },
+    { "name": "strategy", "description": "Rate limiting strategy (ip, user, api-key)", "default": "ip" }
+  ],
+  "tags": ["rate-limiting", "middleware", "security", "backend"]
+}

package/src/config/spec-templates/stripe-payments/spec.md

@@ -0,0 +1,32 @@
+# Stripe Payments Integration
+
+## Overview
+Integrate Stripe payment processing to support one-time payments and subscriptions for {{plan_name}} in {{currency}} currency.
+
+## Acceptance Criteria
+
+### AC-1: Checkout Session Creation
+- Create a Stripe checkout session for {{plan_name}} with currency {{currency}}
+- Return a redirect URL to the hosted Stripe payment page
+- Store the session ID for reconciliation
+
+### AC-2: Webhook Processing
+- Handle incoming Stripe events at {{webhook_endpoint}}
+- Verify HMAC signature using `Stripe-Signature` header
+- Process `checkout.session.completed` and `invoice.payment_failed` events
+- Idempotently handle duplicate webhook deliveries
+
+### AC-3: Subscription Management
+- Retrieve subscription status from Stripe API
+- Cancel subscriptions on user request
+- Expose subscription status in user profile response
+
+### AC-4: Error Handling
+- Return user-friendly errors when payment fails
+- Log Stripe API errors with request IDs for debugging
+- Handle network timeouts with retry logic (max 3 attempts)
+
+## Technical Notes
+- Store Stripe customer IDs and subscription IDs in the database, never card data
+- All prices defined in cents to avoid floating-point errors
+- Use Stripe's idempotency keys for all write operations

package/src/config/spec-templates/stripe-payments/template.json

@@ -0,0 +1,10 @@
+{
+  "name": "stripe-payments",
+  "description": "Stripe payment integration with checkout sessions, webhooks, and subscription management",
+  "variables": [
+    { "name": "currency", "description": "Default currency code (e.g. usd, eur)", "default": "usd" },
+    { "name": "plan_name", "description": "Name of the subscription plan or product", "default": "Pro Plan" },
+    { "name": "webhook_endpoint", "description": "Path for the Stripe webhook endpoint", "default": "/api/webhooks/stripe" }
+  ],
+  "tags": ["payments", "stripe", "subscriptions", "backend"]
+}

package/src/config/spec-templates/webhook-system/spec.md

@@ -0,0 +1,36 @@
+# Webhook System
+
+## Overview
+Webhook delivery system with event subscriptions, HMAC signature verification via `{{signature_header}}`, retry logic (max {{max_retries}} attempts), and {{timeout_seconds}}s per request timeout.
+
+## Acceptance Criteria
+
+### AC-1: Subscription Management
+- Allow consumers to register webhook endpoints with target URL and event types
+- Validate that the target URL is reachable via a test ping on registration
+- Store subscriptions with status (active, paused, failed)
+
+### AC-2: Event Delivery
+- Deliver event payloads via HTTP POST to registered endpoints
+- Include `{{signature_header}}` HMAC-SHA256 signature in each request
+- Set request timeout to {{timeout_seconds}} seconds per attempt
+
+### AC-3: Retry Logic
+- Retry failed deliveries up to {{max_retries}} times
+- Use exponential backoff: 1min, 5min, 30min between retries
+- Mark subscription as `failed` after exhausting all retries
+
+### AC-4: Signature Verification (Consumer Guide)
+- Compute HMAC-SHA256 of the raw request body using the shared secret
+- Compare computed signature with the value in `{{signature_header}}`
+- Reject requests with invalid or missing signatures
+
+### AC-5: Delivery Log
+- Store delivery attempts: endpoint, event type, response code, latency, attempt number
+- Expose delivery history per subscription via admin API
+- Purge logs older than 30 days automatically
+
+## Technical Notes
+- Use a unique shared secret per subscription — never reuse across consumers
+- Process delivery queue asynchronously to avoid blocking event producers
+- Validate registered URLs against an allowlist to prevent SSRF attacks

package/src/config/spec-templates/webhook-system/template.json

@@ -0,0 +1,10 @@
+{
+  "name": "webhook-system",
+  "description": "Webhook system with event subscriptions, HMAC signature verification, and retry logic",
+  "variables": [
+    { "name": "max_retries", "description": "Maximum delivery retry attempts", "default": "3" },
+    { "name": "timeout_seconds", "description": "HTTP request timeout per delivery attempt", "default": "10" },
+    { "name": "signature_header", "description": "HTTP header name for HMAC signature", "default": "X-Webhook-Signature" }
+  ],
+  "tags": ["webhooks", "events", "backend", "integrations"]
+}