{"id":15107189,"url":"https://github.com/unredacted/freesocks-control-plane","last_synced_at":"2025-10-23T02:30:58.503Z","repository":{"id":243486091,"uuid":"812566933","full_name":"unredacted/freesocks-control-plane","owner":"unredacted","description":"The control plane that makes FreeSocks work","archived":false,"fork":false,"pushed_at":"2024-10-10T07:03:49.000Z","size":80,"stargazers_count":19,"open_issues_count":3,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-01-30T16:52:21.221Z","etag":null,"topics":["censorship-circumvention","censorship-resistance","censorship-resistant","cloudflare-worker","cloudflare-workers","outline","outline-vpn","shadowsocks"],"latest_commit_sha":null,"homepage":"https://freesocks.org","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/unredacted.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","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},"funding":{"github":"unredacted","patreon":"unredacted_org","open_collective":"unredacted","ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":"unredacted","issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2024-06-09T09:10:00.000Z","updated_at":"2025-01-17T22:03:23.000Z","dependencies_parsed_at":"2024-06-09T10:31:17.578Z","dependency_job_id":"2cb70c28-d790-40d2-a0b9-0d5ffc082db7","html_url":"https://github.com/unredacted/freesocks-control-plane","commit_stats":null,"previous_names":["unredacted/freesocks-control-plane"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unredacted%2Ffreesocks-control-plane","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unredacted%2Ffreesocks-control-plane/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unredacted%2Ffreesocks-control-plane/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unredacted%2Ffreesocks-control-plane/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/unredacted","download_url":"https://codeload.github.com/unredacted/freesocks-control-plane/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237763855,"owners_count":19362310,"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":["censorship-circumvention","censorship-resistance","censorship-resistant","cloudflare-worker","cloudflare-workers","outline","outline-vpn","shadowsocks"],"created_at":"2024-09-25T21:20:31.884Z","updated_at":"2025-10-23T02:30:58.195Z","avatar_url":"https://github.com/unredacted.png","language":"JavaScript","funding_links":["https://github.com/sponsors/unredacted","https://patreon.com/unredacted_org","https://opencollective.com/unredacted","https://liberapay.com/unredacted"],"categories":[],"sub_categories":[],"readme":"# FreeSocks Control Plane (FCP)\n\nThis is the (control plane) code behind [FreeSocks](https://freesocks.org) a service that provides free, open \u0026 uncensored Outline (Shadowsocks) proxies to people in countries experiencing a high level of Internet censorship.\n\nThe FreeSocks Control Plane (FCP) utilizes [Cloudflare Workers](https://workers.cloudflare.com/) and is written in JavaScript. This repository allows you to stand up your own FreeSocks-like Outline access key distribution platform, and provides insight into how FreeSocks works.\n\nThe FreeSocks Control Plane consists of several core components:\n\n- GET Script (src/handlers/get.js) - distributes Outline access keys to users.\n- DELETE Script (src/handlers/delete.js) - deletes access keys that have not been used after a defined number of days.\n- UPDATE Script (src/handlers/update.js) - updates KV JSON data to track the state of access keys (creation, deletion, last used and if a key is currently in use).\n- LIST Script (src/handlers/list.js) - lists access key data from KV for admins.\n\n## Prerequisites\n\n- A Cloudflare account with access to the Workers platform.\n- The creation of several Workers KV namespaces, which are to be defined in the `wrangler.toml` environment variables.\n- A zone on Cloudflare to be used for the FreeSocks Control Plane.\n- Cloudflare [wrangler](https://developers.cloudflare.com/workers/wrangler/install-and-update/).\n- Ensure you are logged in to Cloudflare with [wrangler](https://developers.cloudflare.com/workers/wrangler/commands/#login)\n\n## Defining environment variables\n\nCheck `wrangler-example.toml` for example variables.\n\nMake a copy of `wrangler-example.toml` to `wrangler.toml` then edit them depending on your requirements.\n\nSet sensitive variables with `wrangler secret`.\n\nSet required secrets:\n\n```\n# For get.js\nwrangler secret put TURNSTILE_SITE_KEY\nwrangler secret put TURNSTILE_SECRET_KEY\n\n# For delete.js\nwrangler secret put SECRET_AUTH_TOKEN\nwrangler secret put VAR_CF_ACCESS_CLIENT_ID\nwrangler secret put VAR_CF_ACCESS_CLIENT_SECRET\n```\n\n## How to deploy\n\nTo deploy the FCP, you can run:\n\n```\nwrangler deploy\n```\n\n## Updating your FCP code\n\n1. Check for breaking changes since you last deployed your Worker, and fix if needed.\n2. Pull the latest code from the repository's directory you have on your system:\n\n```\ngit pull\n```\n\nDeploy the Worker:\n\n```\nwrangler deploy\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funredacted%2Ffreesocks-control-plane","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funredacted%2Ffreesocks-control-plane","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funredacted%2Ffreesocks-control-plane/lists"}