{"id":18772744,"url":"https://github.com/sctg-development/turgeand-messaging","last_synced_at":"2025-04-13T08:32:05.630Z","repository":{"id":247053005,"uuid":"824902805","full_name":"sctg-development/turgeand-messaging","owner":"sctg-development","description":"Cloudflare Worker for handling Twilio SMS webhooks, storing messages in KV, and providing secure retrieval.","archived":false,"fork":false,"pushed_at":"2024-07-06T09:52:58.000Z","size":87,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-07-06T10:25:53.553Z","etag":null,"topics":["cloudflare","cloudflare-workers","twilio","twilio-sms"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sctg-development.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-07-06T08:55:19.000Z","updated_at":"2024-07-06T10:26:02.257Z","dependencies_parsed_at":"2024-07-06T10:25:58.594Z","dependency_job_id":"a9e2d844-ed81-4bef-a2e8-31026833f3e3","html_url":"https://github.com/sctg-development/turgeand-messaging","commit_stats":null,"previous_names":["sctg-development/turgeand-messaging"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sctg-development%2Fturgeand-messaging","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sctg-development%2Fturgeand-messaging/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sctg-development%2Fturgeand-messaging/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sctg-development%2Fturgeand-messaging/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sctg-development","download_url":"https://codeload.github.com/sctg-development/turgeand-messaging/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223576699,"owners_count":17167910,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloudflare","cloudflare-workers","twilio","twilio-sms"],"created_at":"2024-11-07T19:30:04.296Z","updated_at":"2024-11-07T19:30:05.173Z","avatar_url":"https://github.com/sctg-development.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Twilio SMS Cloudflare Worker\n\nThis Cloudflare Worker is designed to handle incoming SMS messages from Twilio webhooks and store them in Cloudflare KV (Key-Value) storage. It also provides functionality to retrieve stored messages for a given destination number.\n\n[![Run CI tests with Vitest](https://github.com/sctg-development/turgeand-messaging/actions/workflows/vitest.yml/badge.svg)](https://github.com/sctg-development/turgeand-messaging/actions/workflows/vitest.yml)\n\n## Features\n\n- Receives and stores incoming SMS data from Twilio webhooks\n- Retrieves stored SMS messages for a specific recipient\n- Basic authentication for accessing stored messages\n\n## Setup\n\n1. Deploy this worker to your Cloudflare account.\n2. Set up a KV namespace called `TWILIO_KV` in your Cloudflare account.\n3. Configure your Twilio account to send webhook requests to your worker's URL for incoming SMS messages.\n\n## Usage\n\n### Storing Incoming SMS\n\nWhen Twilio receives an SMS, it will send a POST request to your worker's `/twilio/incoming` endpoint. The worker will store the message data in the KV store with a key in the format: `INCOMING:{recipient_number}:{MessageSid}`.\n\nSimulate Twilio webhook request with cURL:\n\n```bash\ncurl -i -X POST \"${WORKER_URL}${TWILIO_URL}\" \\\n  -F \"MessageSid=$MESSAGE_SID\" \\\n  -F \"From=+14017122661\" \\\n  -F \"To=+15558675310\" \\\n  -F \"Body=Test message\"\n```\n\n### Retrieving Stored Messages\n\nTo retrieve stored messages for a specific recipient:\n\n1. Send a GET request to `/twilio/read?to={recipient_number}`\n2. Include an `Authorization` header with Basic Auth credentials\n\nExample:\n\n```http\nGET /twilio/read?to=+1234567890\nAuthorization: Basic base64(username:password)\n```\n\nThe worker will return a JSON array of stored messages for the specified recipient.\n\n## Authentication\n\nThe worker uses basic authentication to protect access to stored messages. To set up authentication:\n\n1. Generate a bcrypt hash of the desired password\n2. Store the hash in the KV store with the key `USER:{username}`\n\nSample code to generate a bcrypt hash with a 12 cost factor using `htpasswd`:\n\n```bash\npassword=\"your_password\"\nbcrypted=$(htpasswd -nbB -C 12 user $password | awk -F: '{print $2}')\necho $bcrypted\n```\n\n## Error Handling\n\n- 400 Bad Request: Returned if the MessageSid is missing from the Twilio webhook\n- 401 Unauthorized: Returned if authentication fails when retrieving messages\n- 405 Method Not Allowed: Returned for unsupported HTTP methods\n\n## Dependencies\n\n- `@cloudflare/workers-types`: TypeScript definitions for Cloudflare Workers\n- `bcrypt-ts`: TypeScript implementation of bcrypt for password hashing\n\n## Development\n\nTo modify or extend this worker:\n\n1. Clone the repository\n2. Install dependencies with `npm install`\n3. Make your changes to `index.ts`\n4. Test your changes locally using Wrangler\n5. Deploy the updated worker to Cloudflare\n\n### Sample wrangler.toml\n\nOur wrangler.toml is not included in the repository. Here is a sample configuration, just edit your kv namespace id and name to match your own configuration:\n\n```toml\n#:schema node_modules/wrangler/config-schema.json\nname = \"turgeand-messaging\"\nmain = \"src/index.ts\"\ncompatibility_date = \"2024-07-01\"\ncompatibility_flags = [\"nodejs_compat\"]\nkv_namespaces = [\n  { binding = \"TWILIO_KV\", id = \"085b7cbf251c15d1c2e1e5c063ac86b5\" }\n]\n```\n\n## Security Considerations\n\n- Ensure that your Cloudflare Worker URL is properly secured and only accessible by Twilio\n- Regularly rotate your authentication credentials\n- Monitor your worker's logs for any suspicious activity\n\n## License\n\nThis project is licensed under the Affero GPL v3 License - see the [LICENSE](LICENSE.md) file for details.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsctg-development%2Fturgeand-messaging","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsctg-development%2Fturgeand-messaging","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsctg-development%2Fturgeand-messaging/lists"}