@intentsolutionsio/vercel-pack 1.0.0 → 1.0.3

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

@@ -1,140 +1,230 @@
 ---
 name: vercel-security-basics
-description: |
-  Apply Vercel security best practices for secrets and access control.
-  Use when securing API keys, implementing least privilege access,
+description: 'Apply Vercel security best practices for secrets, headers, and access
+  control.
+
+  Use when securing API keys, configuring security headers,
+
   or auditing Vercel security configuration.
+
   Trigger with phrases like "vercel security", "vercel secrets",
-  "secure vercel", "vercel API key security".
-allowed-tools: Read, Write, Grep
+
+  "secure vercel", "vercel headers", "vercel CSP".
+
+  '
+allowed-tools: Read, Write, Edit, Bash(vercel:*), Grep
 version: 1.0.0
 license: MIT
 author: Jeremy Longshore <jeremy@intentsolutions.io>
+tags:
+- saas
+- vercel
+- security
+- headers
+- secrets
+compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
 ---
-
 # Vercel Security Basics
 
 ## Overview
-Security best practices for Vercel API keys, tokens, and access control.
+
+Secure Vercel deployments with proper secret management, security headers, deployment protection, and access token hygiene. Covers environment variable scoping, Content Security Policy, and preventing common secret exposure patterns.
 
 ## Prerequisites
-- Vercel SDK installed
-- Understanding of environment variables
+
+- Vercel CLI installed and authenticated
 - Access to Vercel dashboard
+- Understanding of HTTP security headers
 
 ## Instructions
 
-### Step 1: Configure Environment Variables
+### Step 1: Secret Management with Environment Variables
+
 ```bash
-# .env (NEVER commit to git)
-VERCEL_API_KEY=sk_live_***
-VERCEL_SECRET=***
-
-# .gitignore
-.env
-.env.local
-.env.*.local
+# Add secrets scoped to specific environments
+vercel env add DATABASE_URL production
+vercel env add DATABASE_URL preview
+vercel env add DATABASE_URL development
+
+# Use 'sensitive' type — values hidden in dashboard and logs
+vercel env add API_SECRET production --sensitive
+
+# Via REST API
+curl -X POST "https://api.vercel.com/v9/projects/my-app/env" \
+  -H "Authorization: Bearer $VERCEL_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "key": "API_SECRET",
+    "value": "sk-secret-value",
+    "type": "sensitive",
+    "target": ["production"]
+  }'
 ```
 
-### Step 2: Implement Secret Rotation
-```bash
-# 1. Generate new key in Vercel dashboard
-# 2. Update environment variable
-export VERCEL_API_KEY="new_key_here"
+**Critical rule:** Never prefix secrets with `NEXT_PUBLIC_`. Variables starting with `NEXT_PUBLIC_` are inlined into the client JavaScript bundle and visible to anyone.
+
+### Step 2: Security Headers via vercel.json
+
+```json
+{
+  "headers": [
+    {
+      "source": "/(.*)",
+      "headers": [
+        { "key": "X-Content-Type-Options", "value": "nosniff" },
+        { "key": "X-Frame-Options", "value": "DENY" },
+        { "key": "X-XSS-Protection", "value": "1; mode=block" },
+        { "key": "Referrer-Policy", "value": "strict-origin-when-cross-origin" },
+        { "key": "Permissions-Policy", "value": "camera=(), microphone=(), geolocation=()" },
+        {
+          "key": "Strict-Transport-Security",
+          "value": "max-age=63072000; includeSubDomains; preload"
+        },
+        {
+          "key": "Content-Security-Policy",
+          "value": "default-src 'self'; script-src 'self' 'unsafe-inline' https://vercel.live; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' https://fonts.gstatic.com; connect-src 'self' https://api.vercel.com"
+        }
+      ]
+    }
+  ]
+}
+```
 
-# 3. Verify new key works
-curl -H "Authorization: Bearer ${VERCEL_API_KEY}" \
-  https://api.vercel.com/health
+### Step 3: Security Headers via Edge Middleware
 
-# 4. Revoke old key in dashboard
+```typescript
+// middleware.ts
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+
+export function middleware(request: NextRequest) {
+  const response = NextResponse.next();
+
+  // Security headers
+  response.headers.set('X-Content-Type-Options', 'nosniff');
+  response.headers.set('X-Frame-Options', 'DENY');
+  response.headers.set('Referrer-Policy', 'strict-origin-when-cross-origin');
+  response.headers.set(
+    'Strict-Transport-Security',
+    'max-age=63072000; includeSubDomains; preload'
+  );
+
+  // Remove server version headers
+  response.headers.delete('X-Powered-By');
+
+  return response;
+}
 ```
 
-### Step 3: Apply Least Privilege
-| Environment | Recommended Scopes |
-|-------------|-------------------|
-| Development | `read, deploy` |
-| Staging | `read, write, deploy` |
-| Production | `read, write, deploy, domains` |
+### Step 4: Deployment Protection
 
-## Output
-- Secure API key storage
-- Environment-specific access controls
-- Audit logging enabled
+```json
+// vercel.json
+{
+  "deploymentProtection": {
+    "preview": "vercel-authentication",
+    "optedOutFrom": []
+  }
+}
+```
 
-## 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 |
+Protection options:
 
-## Examples
+- **`vercel-authentication`** — requires Vercel team login to view preview deploys
+- **`standard-protection`** — uses bypass header for automation
+- **Deployment Protection Bypass** — for CI/CD and health checks:
 
-### Service Account Pattern
-```typescript
-const clients = {
-  reader: new VercelClient({
-    apiKey: process.env.VERCEL_READ_KEY,
-  }),
-  writer: new VercelClient({
-    apiKey: process.env.VERCEL_WRITE_KEY,
-  }),
-};
+```bash
+# Generate a bypass secret in Vercel dashboard > Settings > Deployment Protection
+# Use in CI with:
+curl -H "x-vercel-protection-bypass: your-bypass-secret" \
+  https://my-app-preview.vercel.app/api/health
 ```
 
-### Webhook Signature Verification
-```typescript
-import crypto from 'crypto';
+### Step 5: Access Token Best Practices
 
-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));
-}
+```bash
+# Create scoped tokens — restrict to one team and project
+# Settings > Tokens > Create Token:
+# - Scope: Team → your-team
+# - Expiration: 90 days (for CI)
+# - Permissions: Deployment-only (no team admin)
+
+# Rotate tokens on a schedule
+# In CI (GitHub Actions):
+# Store as GitHub Secret: VERCEL_TOKEN
+# Set expiry alerts in your calendar
 ```
 
-### 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
+Token security rules:
+
+1. Never commit tokens to git — use `.env.local` or CI secrets
+2. Scope tokens to the minimum required permissions
+3. Set expiration dates (90 days for CI, 30 days for dev)
+4. Rotate immediately if exposed
+5. Use separate tokens per environment/pipeline
+
+### Step 6: API Route Authentication
 
-### Audit Logging
 ```typescript
-interface AuditEntry {
-  timestamp: Date;
-  action: string;
-  userId: string;
-  resource: string;
-  result: 'success' | 'failure';
-  metadata?: Record<string, any>;
+// api/protected.ts
+import type { VercelRequest, VercelResponse } from '@vercel/node';
+
+export default function handler(req: VercelRequest, res: VercelResponse) {
+  // Verify API key from header
+  const apiKey = req.headers['x-api-key'];
+  if (!apiKey || apiKey !== process.env.INTERNAL_API_KEY) {
+    return res.status(401).json({ error: 'Unauthorized' });
+  }
+
+  // Verify origin for CORS
+  const origin = req.headers.origin;
+  const allowedOrigins = (process.env.ALLOWED_ORIGINS ?? '').split(',');
+  if (origin && !allowedOrigins.includes(origin)) {
+    return res.status(403).json({ error: 'Forbidden origin' });
+  }
+
+  res.json({ data: 'protected content' });
 }
+```
 
-async function auditLog(entry: Omit<AuditEntry, 'timestamp'>): Promise<void> {
-  const log: AuditEntry = { ...entry, timestamp: new Date() };
+## Security Checklist
 
-  // Log to Vercel analytics
-  await vercelClient.track('audit', log);
+| Check | Status |
+|-------|--------|
+| No secrets in `NEXT_PUBLIC_*` variables | Required |
+| Sensitive env vars use `type: sensitive` | Required |
+| Security headers configured | Required |
+| HSTS enabled with preload | Recommended |
+| Preview deployments protected | Recommended |
+| Access tokens scoped and rotated | Required |
+| CSP configured for your domains | Recommended |
+| `.env.local` in `.gitignore` | Required |
 
-  // Also log locally for compliance
-  console.log('[AUDIT]', JSON.stringify(log));
-}
+## Output
 
-// Usage
-await auditLog({
-  action: 'vercel.api.call',
-  userId: currentUser.id,
-  resource: '/v1/resource',
-  result: 'success',
-});
-```
+- Environment variables properly scoped and typed as sensitive
+- Security headers applied to all responses
+- Deployment protection enabled for preview URLs
+- Access tokens scoped with expiration dates
+
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| Secret visible in client bundle | Prefixed with `NEXT_PUBLIC_` | Remove prefix, redeploy, rotate the secret |
+| CSP blocking resources | Policy too restrictive | Add the blocked domain to the relevant directive |
+| Preview accessible without auth | Deployment protection disabled | Enable in vercel.json or dashboard |
+| Token expired | Past expiration date | Generate new token, update CI secrets |
 
 ## Resources
-- [Vercel Security Guide](https://vercel.com/docs/security)
-- [Vercel API Scopes](https://vercel.com/docs/scopes)
+
+- [Vercel Security](https://vercel.com/docs/security)
+- [Deployment Protection](https://vercel.com/docs/security/deployment-protection)
+- [Environment Variables](https://vercel.com/docs/environment-variables)
+- [Security Headers](https://vercel.com/docs/headers)
+- [Access Tokens](https://vercel.com/docs/rest-api#creating-an-access-token)
 
 ## Next Steps
-For production deployment, see `vercel-prod-checklist`.
+
+For production deployment checklist, see `vercel-prod-checklist`.

package/skills/vercel-security-basics/references/errors.md

@@ -0,0 +1,10 @@
+# Error Handling Reference
+
+| Security Issue | Detection | Mitigation |
+|----------------|-----------|------------|
+| Exposed API key | Git scanning | Rotate immediately |
+| Excessive scopes | Audit logs | Reduce permissions |
+| Missing rotation | Key age check | Schedule rotation |
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/vercel-security-basics/references/examples.md

@@ -0,0 +1,70 @@
+## 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',
+});
+```
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/vercel-security-basics/references/implementation.md

@@ -0,0 +1,39 @@
+## Implementation Guide
+
+### 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` |
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*