Update to Twilio Developer Kit

{
  "description": "Secure Twilio applications against common attacks. Covers credential management (API keys vs auth tokens), request validation (webhook signature verification), PCI DSS compliance, HIPAA account requirements, SMS pumping prevention, geo-permissions, and account isolation patterns. Use this skill when developers are building or deploying Twilio apps.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 231
    }
  ],
  "name": "twilio-security-hardening",
  "skill_md_contents": "---\nname: twilio-security-hardening\ndescription: >\n  Secure Twilio applications against common attacks. Covers credential\n  management (API keys vs auth tokens), request validation (webhook\n  signature verification), PCI DSS compliance, HIPAA account requirements,\n  SMS pumping prevention, geo-permissions, and account isolation patterns.\n  Use this skill when developers are building or deploying Twilio apps.\n---\n\n## Overview\n\nSecurity hardening is an **ongoing** concern — not a one-time setup. This skill covers account-level security decisions and application-level protection patterns that prevent credential leaks, fraud, and compliance violations.\n\n**Lifecycle:** Choose numbers (`twilio-numbers-senders`) → Register (`twilio-compliance-onboarding`) → Follow traffic rules (`twilio-compliance-traffic`) → Secure everything (this skill)\n\n---\n\n## Credential Management\n\n### API Keys vs Auth Tokens\n\n| Credential | Scope | Revocable | Use when |\n|-----------|-------|-----------|----------|\n| **Auth Token** | Full account access | Only by rotating (invalidates ALL API keys) | Never in production — use API keys instead |\n| **API Key + Secret** | Scoped, revocable individually | Yes — revoke one without affecting others | Production applications, CI/CD, server-side code |\n| **Access Tokens** | Short-lived, client-specific | Expire automatically | Client-side SDKs (Voice, Video, Conversations) |\n\n**Critical gotcha:** Rotating your Auth Token **invalidates ALL existing API keys**. This is a one-way door that can break every integration simultaneously. Use API keys from the start so you never need to rotate the Auth Token.\n\n### Best Practices\n\n- Store credentials in environment variables or a secrets manager — never in code\n- Use different API keys per application/environment\n- Rotate API keys on a schedule (quarterly minimum, monthly for HIPAA)\n- Use sub-accounts to isolate customer credentials for ISV platforms — see `twilio-account-setup`\n\n**Docs:** See `twilio-iam-auth-setup` for full credential setup patterns.\n\n---\n\n## Request Validation (Webhook Security)\n\nVerify that webhook requests actually come from Twilio — not spoofed by attackers.\n\n### X-Twilio-Signature Validation\n\nAlways use the SDK validator — don't implement HMAC-SHA1 manually:\n\n**Node.js**\n```javascript\nconst twilio = require(\"twilio\");\n\napp.post(\"/sms\", (req, res) => {\n    const valid = twilio.validateRequest(\n        process.env.TWILIO_AUTH_TOKEN,\n        req.headers[\"x-twilio-signature\"],\n        `https://yourdomain.com/sms`,\n        req.body\n    );\n    if (!valid) return res.status(403).send(\"Forbidden\");\n    // Process webhook...\n});\n```\n\n**Common mistakes:**\n- Using HTTP URL when Twilio sends to HTTPS (URL must match exactly)\n- Forgetting to include query string parameters in validation URL\n- Not validating in production because \"it worked in dev without it\"\n\n**Docs:** See `twilio-webhook-architecture` for full webhook security patterns.\n\n---\n\n## Account-Level Compliance\n\n### PCI DSS (Payment Card Industry)\n\n**PCI Mode is IRREVERSIBLE and account-wide.** Once enabled, it cannot be disabled — ever.\n\n- All recordings are encrypted\n- Transcript access is restricted\n- Affects every service on the account\n\n**Recommendation:** If you need PCI compliance for one use case, create a **separate sub-account** dedicated to payment-related calls. See `twilio-account-setup` for sub-account patterns.\n\nFor call recording during payment, pause recording when the customer gives card numbers:\n```python\nclient.calls(call_sid).recordings(recording_sid).update(status=\"paused\")\n```\n\nOr use the `<Pay>` verb to handle payments without your application touching card data:\n```xml\n<Pay paymentConnector=\"stripe_connector\" chargeAmount=\"49.99\" currency=\"usd\" />\n```\n\n### HIPAA (Healthcare)\n\nBefore handling Protected Health Information (PHI):\n- **Execute a BAA** (Business Associate Agreement) with Twilio — contact your account manager or [submit a sales request](https://www.twilio.com/en-us/help/sales) if you don't have one\n- **Encrypt all recordings** containing PHI\n- **Minimize PHI in TTS** — don't speak full patient details via `<Say>`\n- **Rotate API keys** on a regular schedule\n- **Restrict access** to recordings and transcripts\n\n---\n\n## Fraud Prevention\n\n### SMS Pumping Protection\n\nAttackers trigger thousands of OTP messages to premium-rate numbers, generating toll charges.\n\n**Layered defense:**\n1. **Twilio Verify Fraud Guard** — built-in fraud detection (enable on Verify Service)\n2. **Lookup pre-check** — call `twilio-lookup-phone-intelligence` to check line type + SMS pumping risk score before sending\n3. **Geo-permissions** — restrict SMS/voice to countries where you have customers ([Console > Messaging > Geo Permissions](https://console.twilio.com))\n4. **Rate limiting** — limit verification attempts per IP, per phone number, per time window\n\n### Geo-Permissions\n\nRestrict which countries can receive messages or calls from your account:\n- Disable all countries you don't serve (SMS and Voice separately)\n- Re-enable only as needed — [configure in Console](https://www.twilio.com/docs/messaging/guides/sms-geo-permissions)\n- This is the single most effective anti-fraud measure for SMS pumping\n\n**SMS pumping impact:** Incidents can climb into tens of thousands of dollars. Twilio does not publish most-targeted prefixes — the general guidance is to restrict message termination to countries where you do business via geo-permissions. Customers using Fraud Guard can view estimated fraud savings in their [Fraud Guard reports](https://www.twilio.com/docs/verify/preventing-toll-fraud/sms-fraud-guard).\n\n---\n\n## Common Mistakes\n\n1. **Auth Token in code** — Pushed to GitHub, leaked. Use environment variables + API keys.\n2. **No webhook validation** — Attackers can send fake webhook requests to your endpoints.\n3. **PCI Mode on main account** — Irreversible. Use a sub-account for payment use cases.\n4. **No geo-permissions** — Account is open to SMS pumping from any country.\n5. **Auth Token rotation without planning** — Breaks all API keys simultaneously.\n\n---\n\n## Credential Rotation (Zero-Downtime)\n\nBoth API keys and Auth Tokens follow the same workflow:\n\n1. **Create secondary** — generate a new API key (or note the new Auth Token)\n2. **Operationalize secondary** — deploy the new credential to all services\n3. **Promote secondary to primary** — verify all traffic uses the new credential\n4. **Delete old primary** — revoke the previous credential\n\nManage keys at: `https://console.twilio.com/account/keys-credentials/api-keys` (per account).\n\n**Key enabler: use a secrets manager** (AWS Secrets Manager, HashiCorp Vault, etc.) to inject credentials at runtime. This makes rotation near-instantaneous with no downtime — no code changes, no redeployments. Organizations that hard-code credentials into repos, deployment scripts, or `.env` files must manually update every location before deleting the old key.\n\nFor ISVs managing many sub-accounts, automate this with the API Keys REST API across accounts.\n\n---\n\n## Next Steps\n\n- **Credential setup and API key management:** `twilio-iam-auth-setup`\n- **Webhook security and signature validation:** `twilio-webhook-architecture`\n- **Account structure and sub-accounts:** `twilio-account-setup`\n- **Phone intelligence for fraud scoring:** `twilio-lookup-phone-intelligence`\n- **Traffic compliance rules:** `twilio-compliance-traffic`\n"
}