@intentsolutionsio/vercel-pack 1.0.0

package/skills/vercel-security-basics/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: vercel-security-basics
+description: |
+  Apply Vercel security best practices for secrets and access control.
+  Use when securing API keys, implementing least privilege access,
+  or auditing Vercel security configuration.
+  Trigger with phrases like "vercel security", "vercel secrets",
+  "secure vercel", "vercel API key security".
+allowed-tools: Read, Write, Grep
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Vercel Security Basics
+
+## Overview
+Security best practices for Vercel API keys, tokens, and access control.
+
+## Prerequisites
+- Vercel SDK installed
+- Understanding of environment variables
+- Access to Vercel dashboard
+
+## Instructions
+
+### Step 1: Configure Environment Variables
+```bash
+# .env (NEVER commit to git)
+VERCEL_API_KEY=sk_live_***
+VERCEL_SECRET=***
+
+# .gitignore
+.env
+.env.local
+.env.*.local
+```
+
+### Step 2: Implement Secret Rotation
+```bash
+# 1. Generate new key in Vercel dashboard
+# 2. Update environment variable
+export VERCEL_API_KEY="new_key_here"
+
+# 3. Verify new key works
+curl -H "Authorization: Bearer ${VERCEL_API_KEY}" \
+  https://api.vercel.com/health
+
+# 4. Revoke old key in dashboard
+```
+
+### Step 3: Apply Least Privilege
+| Environment | Recommended Scopes |
+|-------------|-------------------|
+| Development | `read, deploy` |
+| Staging | `read, write, deploy` |
+| Production | `read, write, deploy, domains` |
+
+## Output
+- Secure API key storage
+- Environment-specific access controls
+- Audit logging enabled
+
+## Error Handling
+| Security Issue | Detection | Mitigation |
+|----------------|-----------|------------|
+| Exposed API key | Git scanning | Rotate immediately |
+| Excessive scopes | Audit logs | Reduce permissions |
+| Missing rotation | Key age check | Schedule rotation |
+
+## Examples
+
+### Service Account Pattern
+```typescript
+const clients = {
+  reader: new VercelClient({
+    apiKey: process.env.VERCEL_READ_KEY,
+  }),
+  writer: new VercelClient({
+    apiKey: process.env.VERCEL_WRITE_KEY,
+  }),
+};
+```
+
+### Webhook Signature Verification
+```typescript
+import crypto from 'crypto';
+
+function verifyWebhookSignature(
+  payload: string, signature: string, secret: string
+): boolean {
+  const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');
+  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
+}
+```
+
+### Security Checklist
+- [ ] API keys in environment variables
+- [ ] `.env` files in `.gitignore`
+- [ ] Different keys for dev/staging/prod
+- [ ] Minimal scopes per environment
+- [ ] Webhook signatures validated
+- [ ] Audit logging enabled
+
+### Audit Logging
+```typescript
+interface AuditEntry {
+  timestamp: Date;
+  action: string;
+  userId: string;
+  resource: string;
+  result: 'success' | 'failure';
+  metadata?: Record<string, any>;
+}
+
+async function auditLog(entry: Omit<AuditEntry, 'timestamp'>): Promise<void> {
+  const log: AuditEntry = { ...entry, timestamp: new Date() };
+
+  // Log to Vercel analytics
+  await vercelClient.track('audit', log);
+
+  // Also log locally for compliance
+  console.log('[AUDIT]', JSON.stringify(log));
+}
+
+// Usage
+await auditLog({
+  action: 'vercel.api.call',
+  userId: currentUser.id,
+  resource: '/v1/resource',
+  result: 'success',
+});
+```
+
+## Resources
+- [Vercel Security Guide](https://vercel.com/docs/security)
+- [Vercel API Scopes](https://vercel.com/docs/scopes)
+
+## Next Steps
+For production deployment, see `vercel-prod-checklist`.

package/skills/vercel-upgrade-migration/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: vercel-upgrade-migration
+description: |
+  Analyze, plan, and execute Vercel SDK upgrades with breaking change detection.
+  Use when upgrading Vercel SDK versions, detecting deprecations,
+  or migrating to new API versions.
+  Trigger with phrases like "upgrade vercel", "vercel migration",
+  "vercel breaking changes", "update vercel SDK", "analyze vercel version".
+allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(git:*)
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Vercel Upgrade & Migration
+
+## Overview
+Guide for upgrading Vercel SDK versions and handling breaking changes.
+
+## Prerequisites
+- Current Vercel SDK installed
+- Git for version control
+- Test suite available
+- Staging environment
+
+## Instructions
+
+### Step 1: Check Current Version
+```bash
+npm list vercel
+npm view vercel version
+```
+
+### Step 2: Review Changelog
+```bash
+open https://github.com/vercel/vercel/releases
+```
+
+### Step 3: Create Upgrade Branch
+```bash
+git checkout -b upgrade/vercel-sdk-vX.Y.Z
+npm install vercel@latest
+npm test
+```
+
+### Step 4: Handle Breaking Changes
+Update import statements, configuration, and method signatures as needed.
+
+## Output
+- Updated SDK version
+- Fixed breaking changes
+- Passing test suite
+- Documented rollback procedure
+
+## Error Handling
+| SDK Version | API Version | Node.js | Breaking Changes |
+|-------------|-------------|---------|------------------|
+| 3.x | 2024-01 | 18+ | Major refactor |
+| 2.x | 2023-06 | 16+ | Auth changes |
+| 1.x | 2022-01 | 14+ | Initial release |
+
+## Examples
+
+### Import Changes
+```typescript
+// Before (v1.x)
+import { Client } from 'vercel';
+
+// After (v2.x)
+import { VercelClient } from 'vercel';
+```
+
+### Configuration Changes
+```typescript
+// Before (v1.x)
+const client = new Client({ key: 'xxx' });
+
+// After (v2.x)
+const client = new VercelClient({
+  apiKey: 'xxx',
+});
+```
+
+### Rollback Procedure
+```bash
+npm install vercel@1.x.x --save-exact
+```
+
+### Deprecation Handling
+```typescript
+// Monitor for deprecation warnings in development
+if (process.env.NODE_ENV === 'development') {
+  process.on('warning', (warning) => {
+    if (warning.name === 'DeprecationWarning') {
+      console.warn('[Vercel]', warning.message);
+      // Log to tracking system for proactive updates
+    }
+  });
+}
+
+// Common deprecation patterns to watch for:
+// - Renamed methods: client.oldMethod() -> client.newMethod()
+// - Changed parameters: { key: 'x' } -> { apiKey: 'x' }
+// - Removed features: Check release notes before upgrading
+```
+
+## Resources
+- [Vercel Changelog](https://github.com/vercel/vercel/releases)
+- [Vercel Migration Guide](https://vercel.com/docs/migration)
+
+## Next Steps
+For CI integration during upgrades, see `vercel-ci-integration`.

package/skills/vercel-webhooks-events/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: vercel-webhooks-events
+description: |
+  Implement Vercel webhook signature validation and event handling.
+  Use when setting up webhook endpoints, implementing signature verification,
+  or handling Vercel event notifications securely.
+  Trigger with phrases like "vercel webhook", "vercel events",
+  "vercel webhook signature", "handle vercel events", "vercel notifications".
+allowed-tools: Read, Write, Edit, Bash(curl:*)
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Vercel Webhooks & Events
+
+## Overview
+Securely handle Vercel webhooks with signature validation and replay protection.
+
+## Prerequisites
+- Vercel webhook secret configured
+- HTTPS endpoint accessible from internet
+- Understanding of cryptographic signatures
+- Redis or database for idempotency (optional)
+
+## Webhook Endpoint Setup
+
+### Express.js
+```typescript
+import express from 'express';
+import crypto from 'crypto';
+
+const app = express();
+
+// IMPORTANT: Raw body needed for signature verification
+app.post('/webhooks/vercel',
+  express.raw({ type: 'application/json' }),
+  async (req, res) => {
+    const signature = req.headers['x-vercel-signature'] as string;
+    const timestamp = req.headers['x-vercel-timestamp'] as string;
+
+    if (!verifyVercelSignature(req.body, signature, timestamp)) {
+      return res.status(401).json({ error: 'Invalid signature' });
+    }
+
+    const event = JSON.parse(req.body.toString());
+    await handleVercelEvent(event);
+
+    res.status(200).json({ received: true });
+  }
+);
+```
+
+## Signature Verification
+
+```typescript
+function verifyVercelSignature(
+  payload: Buffer,
+  signature: string,
+  timestamp: string
+): boolean {
+  const secret = process.env.VERCEL_WEBHOOK_SECRET!;
+
+  // Reject old timestamps (replay attack protection)
+  const timestampAge = Date.now() - parseInt(timestamp) * 1000;
+  if (timestampAge > 300000) { // 5 minutes
+    console.error('Webhook timestamp too old');
+    return false;
+  }
+
+  // Compute expected signature
+  const signedPayload = `${timestamp}.${payload.toString()}`;
+  const expectedSignature = crypto
+    .createHmac('sha256', secret)
+    .update(signedPayload)
+    .digest('hex');
+
+  // Timing-safe comparison
+  return crypto.timingSafeEqual(
+    Buffer.from(signature),
+    Buffer.from(expectedSignature)
+  );
+}
+```
+
+## Event Handler Pattern
+
+```typescript
+type VercelEventType = 'resource.created' | 'resource.updated' | 'resource.deleted';
+
+interface VercelEvent {
+  id: string;
+  type: VercelEventType;
+  data: Record<string, any>;
+  created: string;
+}
+
+const eventHandlers: Record<VercelEventType, (data: any) => Promise<void>> = {
+  'resource.created': async (data) => { /* handle */ },
+  'resource.updated': async (data) => { /* handle */ },
+  'resource.deleted': async (data) => { /* handle */ }
+};
+
+async function handleVercelEvent(event: VercelEvent): Promise<void> {
+  const handler = eventHandlers[event.type];
+
+  if (!handler) {
+    console.log(`Unhandled event type: ${event.type}`);
+    return;
+  }
+
+  try {
+    await handler(event.data);
+    console.log(`Processed ${event.type}: ${event.id}`);
+  } catch (error) {
+    console.error(`Failed to process ${event.type}: ${event.id}`, error);
+    throw error; // Rethrow to trigger retry
+  }
+}
+```
+
+## Idempotency Handling
+
+```typescript
+import { Redis } from 'ioredis';
+
+const redis = new Redis(process.env.REDIS_URL);
+
+async function isEventProcessed(eventId: string): Promise<boolean> {
+  const key = `vercel:event:${eventId}`;
+  const exists = await redis.exists(key);
+  return exists === 1;
+}
+
+async function markEventProcessed(eventId: string): Promise<void> {
+  const key = `vercel:event:${eventId}`;
+  await redis.set(key, '1', 'EX', 86400 * 7); // 7 days TTL
+}
+```
+
+## Webhook Testing
+
+```bash
+# Use Vercel CLI to send test events
+vercel dev
+
+# Or use webhook.site for debugging
+curl -X POST https://webhook.site/your-uuid \
+  -H "Content-Type: application/json" \
+  -d '{"type": "resource.created", "data": {}}'
+```
+
+## Instructions
+
+### Step 1: Register Webhook Endpoint
+Configure your webhook URL in the Vercel dashboard.
+
+### Step 2: Implement Signature Verification
+Use the signature verification code to validate incoming webhooks.
+
+### Step 3: Handle Events
+Implement handlers for each event type your application needs.
+
+### Step 4: Add Idempotency
+Prevent duplicate processing with event ID tracking.
+
+## Output
+- Secure webhook endpoint
+- Signature validation enabled
+- Event handlers implemented
+- Replay attack protection active
+
+## Error Handling
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Invalid signature | Wrong secret | Verify webhook secret |
+| Timestamp rejected | Clock drift | Check server time sync |
+| Duplicate events | Missing idempotency | Implement event ID tracking |
+| Handler timeout | Slow processing | Use async queue |
+
+## Examples
+
+### Testing Webhooks Locally
+```bash
+# Use ngrok to expose local server
+ngrok http 3000
+
+# Send test webhook
+curl -X POST https://your-ngrok-url/webhooks/vercel \
+  -H "Content-Type: application/json" \
+  -d '{"type": "test", "data": {}}'
+```
+
+## Resources
+- [Vercel Webhooks Guide](https://vercel.com/docs/webhooks)
+- [Webhook Security Best Practices](https://vercel.com/docs/webhooks/security)
+
+## Next Steps
+For performance optimization, see `vercel-performance-tuning`.