opensourceagi/dev-tools-starter-agent/verify-phone-sms

Claude Code and agent skill by opensourceagi/dev-tools-starter-agent

Trust tier 3
  • community
Source check pending

Checking that the SKILL.md file is still in the repository.

Guide to the SMS verification API in packages/verify-phone-sms — the Hono/Cloudflare Workers server, the verifyPhone() function over AWS SNS, /api/send /api/verify /api/sms endpoints, API-key auth, rate limiting, VoIP blocking via external lookup or libphonenumber-js, and wrangler deploys per environment. Use when working with verify-phone-sms or troubleshooting it — 401s from the API key, SMS that never arrives, AWS SNS sandbox and spending limits, sender-id rules, VoIP false positives, or /api/verify accepting any code.

Install

npx vskill@latest install opensourceagi/dev-tools-starter-agent/verify-phone-sms

SKILL.md

Working With verify-phone-sms

The service in packages/verify-phone-sms (npm name verify-phone-sms). Two layers: a verifyPhone() function that sends an SMS through AWS SNS's HTTP API, and a Hono server (@hono/zod-openapi) that exposes it on Cloudflare Workers with auth, rate limiting, and Swagger docs. Exact request/response schemas and options live in API.md.

The one thing to know first

`/api/verify` is a stub. The handler returns { success: true, verified: true } for any input — the source comments say code storage and expiry are left to the integrator. Before this is usable for real auth you must persist the issued code (KV, D1, Durable Object, Redis) keyed by phone number with a TTL, and compare against it. Don't ship the endpoint as-is.

Setup

bash
npm install
npm run dev            # wrangler dev on http://localhost:8787
npm run deploy         # or deploy:staging / deploy:production

Secrets go through Wrangler, not .env, for deployed environments:

bash
wrangler secret put AWS_ACCESS_KEY_ID
wrangler secret put AWS_SECRET_ACCESS_KEY
wrangler secret put API_KEY
VariableDefault
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY—required
AWS_REGIONus-east-1must be a region where SNS SMS is available
API_KEY—required; callers send it as X-API-Key or Authorization: Bearer
SMS_SENDER_IDVerifymax 11 chars, alphanumeric

Picking the right entry point

You wantUse
Send a code from your own backendimport verifyPhone from "verify-phone-sms" — default export, verifyPhone({ phoneNumber, code, … })
Just a VoIP checkimport { isPhoneNumberVoip } from "verify-phone-sms"
A hosted endpointPOST /api/send with X-API-Key
Any non-verification SMSPOST /api/sms with message
Interactive docsGET /docs (Swagger UI) over GET /openapi.json (the spec); both, plus GET / and GET /health, are unauthenticated

Note verifyPhone requires both phoneNumber and code — it sends the code you give it, it does not generate one. The /api/send endpoint generates one for you when the body omits it.

Recipes

VoIP blocking — blockVoip: true plus a detection method:

  • voipDetectionMethod: "api" (default) — external carrier lookup; more accurate, needs network.
  • voipDetectionMethod: "libphonenumber" — local heuristics (toll-free ranges, non-geographic numbers, repeated/sequential digits). Add metadataType: "full" (140 KB vs 75 KB) for real number-type detection instead of pattern guessing.

Formatting — useLibPhoneNumber: true parses and normalizes loosely formatted input (555-123-4567, +44 20 7946 0958) before sending.

Message text — messageTemplate: "Your code is: {code}"; smsType: "Transactional" (default) gets delivery priority over "Promotional".

Auth middleware — applied to /api/* only, and registered above those routes: Hono runs middleware only for handlers defined after it, so moving the app.use("/api/*", …) line below them disables the check without any error. The rate limiter (15-minute window, 100 requests per IP, keyed off CF-Connecting-IP) runs on every route.

Troubleshooting

SymptomCause → fix
/api/verify accepts any codeIt's a mock (see above). Implement storage + comparison before relying on it.
401 UnauthorizedAPI_KEY isn't set for the environment you deployed to, or the header is wrong. Secrets are per-environment — deploy:staging needs its own wrangler secret put --env staging.
SMS never arrives, but the call succeededAn SNS messageId means accepted, not delivered. In the SNS SMS sandbox only verified destination numbers receive messages — verify the number or request production access. Also check the account's monthly SMS spend limit.
Delivery works for US numbers onlyNot every region/route is enabled by default; some countries require sender-id registration or a long code. Check SNS delivery logs per destination country.
Sender ID ignoredMany countries (including the US) override or forbid alphanumeric sender ids. Max 11 alphanumeric characters where it is supported.
Legitimate mobile numbers blocked as VoIPHeuristic detection flags toll-free and pattern-y numbers. Switch to voipDetectionMethod: "api", or metadataType: "full", or turn blockVoip off.
429 from your own APIThe built-in limiter: 100 requests per IP per 15 minutes, before any AWS call.
/openapi.json returns 500 with "Unknown zod object type"@hono/zod-openapi and Zod majors disagree. The package is on Zod 4 and needs @hono/zod-openapi v1+; the v0.19 line bundles a Zod 3-only zod-to-openapi.
/api/* answers without an API keyThe auth middleware is registered after the routes. Move app.use("/api/*", authenticateApiKey) above them.
Works in wrangler dev, fails deployed.env is dev-only; deployed Workers read Wrangler secrets. Set all four values per environment.
AWS SignatureDoesNotMatch / InvalidClientTokenIdWrong key pair, or a region mismatch between the credentials and AWS_REGION.
Codes are logged in responses/api/send echoes the generated code in its response — useful in development, a leak in production. Strip it before exposing the endpoint publicly.

Security

  • Security scanPassed, 90 of 100Pattern checks on the skill's files.
  • Model reviewPassed

See the full security report

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

See evaluation results

Source

Popularity

7-day trend score
0

Not refreshed yet.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/opensourceagi/dev-tools-starter-agent/verify-phone-sms/badge)](https://verified-skill.com/skills/opensourceagi/dev-tools-starter-agent/verify-phone-sms)

Something wrong with this skill or its page? Tell us.