├── .prettierrc
├── .editorconfig
├── package.json
├── vitest.config.js
├── .github
    └── FUNDING.yml
├── test
    └── index.spec.js
├── src
    ├── utils
    │   ├── prometheusQueries.js
    │   ├── authentication.js
    │   ├── errorHandling.js
    │   └── s3Storage.js
    ├── index.js
    ├── config
    │   └── constants.js
    └── handlers
    │   ├── list.js
    │   ├── delete.js
    │   ├── update.js
    │   └── get.js
├── README.md
├── .gitignore
├── wrangler-example.toml
└── LICENSE


/.prettierrc:
--------------------------------------------------------------------------------
1 | {
2 | 	"printWidth": 140,
3 | 	"singleQuote": true,
4 | 	"semi": true,
5 | 	"useTabs": true
6 | }
7 | 


--------------------------------------------------------------------------------
/.editorconfig:
--------------------------------------------------------------------------------
 1 | # http://editorconfig.org
 2 | root = true
 3 | 
 4 | [*]
 5 | indent_style = tab
 6 | end_of_line = lf
 7 | charset = utf-8
 8 | trim_trailing_whitespace = true
 9 | insert_final_newline = true
10 | 
11 | [*.yml]
12 | indent_style = space
13 | 


--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "freesocks-control-plane",
 3 |   "version": "0.0.0",
 4 |   "private": true,
 5 |   "scripts": {
 6 |     "deploy": "wrangler deploy",
 7 |     "dev": "wrangler dev",
 8 |     "start": "wrangler dev",
 9 |     "test": "vitest"
10 |   }
11 | }
12 | 


--------------------------------------------------------------------------------
/vitest.config.js:
--------------------------------------------------------------------------------
 1 | import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";
 2 | 
 3 | export default defineWorkersConfig({
 4 |   test: {
 5 |     poolOptions: {
 6 |       workers: {
 7 |         wrangler: { configPath: "./wrangler.toml" },
 8 |       },
 9 |     },
10 |   },
11 | });
12 | 


--------------------------------------------------------------------------------
/.github/FUNDING.yml:
--------------------------------------------------------------------------------
 1 | github: unredacted
 2 | patreon: unredacted_org
 3 | open_collective: unredacted
 4 | ko_fi: # Replace with a single Ko-fi username
 5 | tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
 6 | community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
 7 | liberapay: unredacted
 8 | issuehunt: # Replace with a single IssueHunt username
 9 | lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
10 | polar: # Replace with a single Polar username
11 | buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
12 | thanks_dev: # Replace with a single thanks.dev username
13 | custom: ['https://unredacted.org/donate/']
14 | 


--------------------------------------------------------------------------------
/test/index.spec.js:
--------------------------------------------------------------------------------
 1 | import { env, createExecutionContext, waitOnExecutionContext, SELF } from "cloudflare:test";
 2 | import { describe, it, expect } from "vitest";
 3 | import worker from "../src";
 4 | 
 5 | describe("Hello World worker", () => {
 6 |   it("responds with Hello World! (unit style)", async () => {
 7 |     const request = new Request("http://example.com");
 8 |     // Create an empty context to pass to `worker.fetch()`.
 9 |     const ctx = createExecutionContext();
10 |     const response = await worker.fetch(request, env, ctx);
11 |     // Wait for all `Promise`s passed to `ctx.waitUntil()` to settle before running test assertions
12 |     await waitOnExecutionContext(ctx);
13 |     expect(await response.text()).toMatchInlineSnapshot(`"Hello World!"`);
14 |   });
15 | 
16 |   it("responds with Hello World! (integration style)", async () => {
17 |    const response = await SELF.fetch("http://example.com");
18 |    expect(await response.text()).toMatchInlineSnapshot(`"Hello World!"`);
19 |  });
20 | });
21 | 


--------------------------------------------------------------------------------
/src/utils/prometheusQueries.js:
--------------------------------------------------------------------------------
 1 | /**
 2 |  * Queries the Prometheus API.
 3 |  * @param {string} promApiEndpoint - The Prometheus API endpoint URL.
 4 |  * @param {string} query - The PromQL query string.
 5 |  * @param {string} clientId - The Cloudflare Access client ID.
 6 |  * @param {string} clientSecret - The Cloudflare Access client secret.
 7 |  * @returns {Object} An object with the query result or error information.
 8 |  */
 9 | export async function queryPrometheus(promApiEndpoint, query, clientId, clientSecret) {
10 |     const queryUrl = `${promApiEndpoint}/api/v1/query?query=${encodeURIComponent(query)}`;
11 |     const headers = {
12 |       'CF-Access-Client-Id': clientId,
13 |       'CF-Access-Client-Secret': clientSecret
14 |     };
15 |   
16 |     try {
17 |       const response = await fetch(queryUrl, { headers });
18 |       if (!response.ok) {
19 |         throw new Error(`Prometheus API request failed: ${response.status} ${response.statusText}`);
20 |       }
21 |   
22 |       const data = await response.json();
23 |       return { success: true, data: data.data.result };
24 |     } catch (error) {
25 |       console.error('Error querying Prometheus:', error);
26 |       return { success: false, error: error.message };
27 |     }
28 |   }


--------------------------------------------------------------------------------
/src/utils/authentication.js:
--------------------------------------------------------------------------------
 1 | /**
 2 |  * Verifies the authentication of a request.
 3 |  * @param {Request} request - The incoming request object.
 4 |  * @param {string} authToken - The expected authentication token.
 5 |  * @returns {boolean} True if authenticated, false otherwise.
 6 |  */
 7 | export async function verifyAuth(request, authToken) {
 8 |     const authHeader = request.headers.get('Authorization');
 9 |     return authHeader && authHeader === `Bearer ${authToken}`;
10 |   }
11 |   
12 |   /**
13 |    * Verifies a Cloudflare Turnstile token.
14 |    * @param {string} token - The Turnstile token to verify.
15 |    * @param {string} secret - The secret key for Turnstile verification.
16 |    * @returns {boolean} True if the token is valid, false otherwise.
17 |    */
18 |   export async function verifyTurnstile(token, secret) {
19 |     try {
20 |       const response = await fetch('https://challenges.cloudflare.com/turnstile/v0/siteverify', {
21 |         method: 'POST',
22 |         headers: {
23 |           'Content-Type': 'application/x-www-form-urlencoded',
24 |         },
25 |         body: `response=${encodeURIComponent(token)}&secret=${encodeURIComponent(secret)}`,
26 |       });
27 |   
28 |       const turnstileValidation = await response.json();
29 |       return turnstileValidation.success;
30 |     } catch (error) {
31 |       console.error('Error verifying Cloudflare Turnstile:', error);
32 |       return false;
33 |     }
34 |   }


--------------------------------------------------------------------------------
/src/utils/errorHandling.js:
--------------------------------------------------------------------------------
 1 | /**
 2 |  * Logs an error message along with optional error details.
 3 |  * @param {string} message - The error message to log.
 4 |  * @param {Error} [error] - Optional Error object with additional details.
 5 |  */
 6 | export function logError(message, error = null) {
 7 |     console.error(`[ERROR] ${message}`);
 8 |     if (error) {
 9 |       console.error(error.stack || error);
10 |     }
11 |   }
12 |   
13 |   /**
14 |    * Logs an informational message.
15 |    * @param {string} message - The message to log.
16 |    */
17 |   export function logInfo(message) {
18 |     console.log(`[INFO] ${message}`);
19 |   }
20 |   
21 |   /**
22 |    * Creates a standardized error response.
23 |    * @param {string} message - The error message.
24 |    * @param {number} status - The HTTP status code.
25 |    * @param {Error} [error] - Optional Error object with additional details.
26 |    * @returns {Response} A Response object with the error details.
27 |    */
28 |   export function handleError(message, status, error = null) {
29 |     logError(message, error);
30 |     const body = JSON.stringify({
31 |       error: message,
32 |       details: error ? error.message : undefined
33 |     });
34 |     return new Response(body, {
35 |       status: status,
36 |       headers: { 'Content-Type': 'application/json' }
37 |     });
38 |   }
39 |   
40 |   /**
41 |    * Wraps an async function with error handling.
42 |    * @param {Function} fn - The async function to wrap.
43 |    * @returns {Function} A wrapped function that catches and handles errors.
44 |    */
45 |   export function withErrorHandling(fn) {
46 |     return async (...args) => {
47 |       try {
48 |         return await fn(...args);
49 |       } catch (error) {
50 |         return handleError('An unexpected error occurred', 500, error);
51 |       }
52 |     };
53 |   }


--------------------------------------------------------------------------------
/src/index.js:
--------------------------------------------------------------------------------
 1 | import { withErrorHandling } from './utils/errorHandling.js';
 2 | 
 3 | // For compatibility with service worker syntax
 4 | addEventListener('fetch', event => {
 5 |   event.respondWith(handleRequest(event.request, event));
 6 | });
 7 | 
 8 | addEventListener('scheduled', event => {
 9 |   event.waitUntil(handleScheduledEvent(event));
10 | });
11 | 
12 | async function handleRequest(request, event) {
13 |   const url = new URL(request.url);
14 |   const path = url.pathname;
15 |   const env = event.env || {};
16 | 
17 |   switch (path) {
18 |     case '/get':
19 |       const getModule = await import('./handlers/get.js');
20 |       return withErrorHandling(getModule.handleRequest)(request, env);
21 |     case '/delete':
22 |       const deleteModule = await import('./handlers/delete.js');
23 |       return withErrorHandling(deleteModule.handleRequest)(request, false, env);
24 |     case '/update':
25 |       const updateModule = await import('./handlers/update.js');
26 |       return withErrorHandling(updateModule.handleRequest)(request, false, env);
27 |     case '/list':
28 |       const listModule = await import('./handlers/list.js');
29 |       return withErrorHandling(listModule.handleRequest)(request, env);
30 |     default:
31 |       return new Response('Not found', { status: 404 });
32 |   }
33 | }
34 | 
35 | async function handleScheduledEvent(event) {
36 |   console.log('Scheduled event triggered');
37 |   const env = event.env || {};
38 |   
39 |   try {
40 | // Temporarily disable delete crons while update script gathers data    
41 | //    const deleteModule = await import('./handlers/delete.js');
42 | //    await deleteModule.handleRequest(null, true, env);
43 |     
44 |     const updateModule = await import('./handlers/update.js');
45 |     await updateModule.handleRequest(null, true, env);
46 |     
47 |     console.log('Scheduled tasks completed successfully');
48 |   } catch (error) {
49 |     console.error('Error in scheduled tasks:', error);
50 |   }
51 | }


--------------------------------------------------------------------------------
/src/config/constants.js:
--------------------------------------------------------------------------------
 1 | export const AUTH_TOKEN = SECRET_AUTH_TOKEN;
 2 | export const turnstileSecretKey = TURNSTILE_SECRET_KEY;
 3 | export const turnstileSiteKey = TURNSTILE_SITE_KEY;
 4 | export const API_ENDPOINTS_NAMESPACE = FREESOCKS_OUTLINE_API_ENDPOINTS;
 5 | export const ACCESS_KEYS_NAMESPACE = FREESOCKS_OUTLINE_ACCESS_KEYS;
 6 | export const PROM_API_ENDPOINTS_NAMESPACE = FREESOCKS_PROM_API_ENDPOINTS;
 7 | export const CF_ACCESS_CLIENT_ID = VAR_CF_ACCESS_CLIENT_ID;
 8 | export const CF_ACCESS_CLIENT_SECRET = VAR_CF_ACCESS_CLIENT_SECRET;
 9 | 
10 | export const EXPIRATION_DAYS = VAR_EXPIRATION_DAYS;
11 | export const PREFIX_DISGUISE = VAR_PREFIX_DISGUISE;
12 | export const WEIGHT_LATENCY = VAR_WEIGHT_LATENCY;
13 | export const WEIGHT_ACCESS_KEY_COUNT = VAR_WEIGHT_ACCESS_KEY_COUNT;
14 | export const API_ENDPOINT_TIMEOUT = VAR_API_ENDPOINT_TIMEOUT;
15 | export const PROM_QUERY_TIME_RANGE = VAR_PROM_QUERY_TIME_RANGE;
16 | 
17 | export const STATE_NAMESPACE = FREESOCKS_STATE_KV;
18 | export const MAX_KEYS_PER_RUN = VAR_MAX_KEYS_PER_RUN;
19 | export const MINIMUM_BYTES_THRESHOLD = VAR_MINIMUM_BYTES_THRESHOLD;
20 | export const MAX_RETRIES = VAR_MAX_RETRIES;
21 | export const RETRY_DELAY = VAR_RETRY_DELAY;
22 | 
23 | // WebSocket configuration
24 | export const WEBSOCKET_ENABLED = VAR_WEBSOCKET_ENABLED === 'true';
25 | export const WEBSOCKET_TCP_PATH = VAR_WEBSOCKET_TCP_PATH || '/tcp';
26 | export const WEBSOCKET_UDP_PATH = VAR_WEBSOCKET_UDP_PATH || '/udp';
27 | export const WEBSOCKET_TLS = VAR_WEBSOCKET_TLS !== 'false';
28 | // Note: WEBSOCKET_DOMAIN is now read from KV namespace per server
29 | 
30 | // S3 storage configuration
31 | export const S3_PROVIDERS_ENABLED = VAR_S3_PROVIDERS_ENABLED === 'true';
32 | export const S3_PROVIDER_COUNT = parseInt(VAR_S3_PROVIDER_COUNT || '0');
33 | export const S3_UPLOAD_MAX_RETRIES = parseInt(VAR_S3_UPLOAD_MAX_RETRIES || '3');
34 | 
35 | // Delete operation configuration
36 | export const DELETE_DRY_RUN = VAR_DELETE_DRY_RUN !== 'false'; // Default to true
37 | export const DELETE_S3_OBJECTS = VAR_DELETE_S3_OBJECTS === 'true'; // Default to false


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # FreeSocks Control Plane (FCP)
 2 | 
 3 | This is the (control plane) code behind [FreeSocks](https://freesocks.org) a service that provides free, open & uncensored Outline (Shadowsocks) proxies to people in countries experiencing a high level of Internet censorship.
 4 | 
 5 | The 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.
 6 | 
 7 | The FreeSocks Control Plane consists of several core components:
 8 | 
 9 | - GET Script (src/handlers/get.js) - distributes Outline access keys to users.
10 | - DELETE Script (src/handlers/delete.js) - deletes access keys that have not been used after a defined number of days.
11 | - 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).
12 | - LIST Script (src/handlers/list.js) - lists access key data from KV for admins.
13 | 
14 | ## Prerequisites
15 | 
16 | - A Cloudflare account with access to the Workers platform.
17 | - The creation of several Workers KV namespaces, which are to be defined in the `wrangler.toml` environment variables.
18 | - A zone on Cloudflare to be used for the FreeSocks Control Plane.
19 | - Cloudflare [wrangler](https://developers.cloudflare.com/workers/wrangler/install-and-update/).
20 | - Ensure you are logged in to Cloudflare with [wrangler](https://developers.cloudflare.com/workers/wrangler/commands/#login)
21 | 
22 | ## Defining environment variables
23 | 
24 | Check `wrangler-example.toml` for example variables.
25 | 
26 | Make a copy of `wrangler-example.toml` to `wrangler.toml` then edit them depending on your requirements.
27 | 
28 | Set sensitive variables with `wrangler secret`.
29 | 
30 | Set required secrets:
31 | 
32 | ```
33 | # For get.js
34 | wrangler secret put TURNSTILE_SITE_KEY
35 | wrangler secret put TURNSTILE_SECRET_KEY
36 | 
37 | # For delete.js
38 | wrangler secret put SECRET_AUTH_TOKEN
39 | wrangler secret put VAR_CF_ACCESS_CLIENT_ID
40 | wrangler secret put VAR_CF_ACCESS_CLIENT_SECRET
41 | ```
42 | 
43 | ## How to deploy
44 | 
45 | To deploy the FCP, you can run:
46 | 
47 | ```
48 | wrangler deploy
49 | ```
50 | 
51 | ## Updating your FCP code
52 | 
53 | 1. Check for breaking changes since you last deployed your Worker, and fix if needed.
54 | 2. Pull the latest code from the repository's directory you have on your system:
55 | 
56 | ```
57 | git pull
58 | ```
59 | 
60 | Deploy the Worker:
61 | 
62 | ```
63 | wrangler deploy
64 | ```
65 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
  1 | # Logs
  2 | 
  3 | logs
  4 | _.log
  5 | npm-debug.log_
  6 | yarn-debug.log*
  7 | yarn-error.log*
  8 | lerna-debug.log*
  9 | .pnpm-debug.log*
 10 | 
 11 | # Diagnostic reports (https://nodejs.org/api/report.html)
 12 | 
 13 | report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
 14 | 
 15 | # Runtime data
 16 | 
 17 | pids
 18 | _.pid
 19 | _.seed
 20 | \*.pid.lock
 21 | 
 22 | # Directory for instrumented libs generated by jscoverage/JSCover
 23 | 
 24 | lib-cov
 25 | 
 26 | # Coverage directory used by tools like istanbul
 27 | 
 28 | coverage
 29 | \*.lcov
 30 | 
 31 | # nyc test coverage
 32 | 
 33 | .nyc_output
 34 | 
 35 | # Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
 36 | 
 37 | .grunt
 38 | 
 39 | # Bower dependency directory (https://bower.io/)
 40 | 
 41 | bower_components
 42 | 
 43 | # node-waf configuration
 44 | 
 45 | .lock-wscript
 46 | 
 47 | # Compiled binary addons (https://nodejs.org/api/addons.html)
 48 | 
 49 | build/Release
 50 | 
 51 | # Dependency directories
 52 | 
 53 | node_modules/
 54 | jspm_packages/
 55 | 
 56 | # Snowpack dependency directory (https://snowpack.dev/)
 57 | 
 58 | web_modules/
 59 | 
 60 | # TypeScript cache
 61 | 
 62 | \*.tsbuildinfo
 63 | 
 64 | # Optional npm cache directory
 65 | 
 66 | .npm
 67 | 
 68 | # Optional eslint cache
 69 | 
 70 | .eslintcache
 71 | 
 72 | # Optional stylelint cache
 73 | 
 74 | .stylelintcache
 75 | 
 76 | # Microbundle cache
 77 | 
 78 | .rpt2_cache/
 79 | .rts2_cache_cjs/
 80 | .rts2_cache_es/
 81 | .rts2_cache_umd/
 82 | 
 83 | # Optional REPL history
 84 | 
 85 | .node_repl_history
 86 | 
 87 | # Output of 'npm pack'
 88 | 
 89 | \*.tgz
 90 | 
 91 | # Yarn Integrity file
 92 | 
 93 | .yarn-integrity
 94 | 
 95 | # dotenv environment variable files
 96 | 
 97 | .env
 98 | .env.development.local
 99 | .env.test.local
100 | .env.production.local
101 | .env.local
102 | 
103 | # parcel-bundler cache (https://parceljs.org/)
104 | 
105 | .cache
106 | .parcel-cache
107 | 
108 | # Next.js build output
109 | 
110 | .next
111 | out
112 | 
113 | # Nuxt.js build / generate output
114 | 
115 | .nuxt
116 | dist
117 | 
118 | # Gatsby files
119 | 
120 | .cache/
121 | 
122 | # Comment in the public line in if your project uses Gatsby and not Next.js
123 | 
124 | # https://nextjs.org/blog/next-9-1#public-directory-support
125 | 
126 | # public
127 | 
128 | # vuepress build output
129 | 
130 | .vuepress/dist
131 | 
132 | # vuepress v2.x temp and cache directory
133 | 
134 | .temp
135 | .cache
136 | 
137 | # Docusaurus cache and generated files
138 | 
139 | .docusaurus
140 | 
141 | # Serverless directories
142 | 
143 | .serverless/
144 | 
145 | # FuseBox cache
146 | 
147 | .fusebox/
148 | 
149 | # DynamoDB Local files
150 | 
151 | .dynamodb/
152 | 
153 | # TernJS port file
154 | 
155 | .tern-port
156 | 
157 | # Stores VSCode versions used for testing VSCode extensions
158 | 
159 | .vscode-test
160 | 
161 | # yarn v2
162 | 
163 | .yarn/cache
164 | .yarn/unplugged
165 | .yarn/build-state.yml
166 | .yarn/install-state.gz
167 | .pnp.\*
168 | 
169 | # wrangler project
170 | 
171 | .dev.vars
172 | .wrangler/
173 | wrangler.toml
174 | 
175 | # Misc
176 | .DS_Store
177 | CLAUDE.md


--------------------------------------------------------------------------------
/src/handlers/list.js:
--------------------------------------------------------------------------------
  1 | import { AUTH_TOKEN, ACCESS_KEYS_NAMESPACE } from '../config/constants.js';
  2 | import { verifyAuth } from '../utils/authentication.js';
  3 | import { handleError, logError } from '../utils/errorHandling.js';
  4 | 
  5 | export async function handleRequest(request) {
  6 |   console.log('List request received');
  7 |   const isAuthorized = await verifyAuth(request, AUTH_TOKEN);
  8 |   if (!isAuthorized) {
  9 |     logError('Unauthorized access attempt to list keys');
 10 |     return handleError('Unauthorized', 401);
 11 |   }
 12 | 
 13 |   try {
 14 |     const filters = getFiltersFromHeaders(request.headers);
 15 |     const { keys, counts } = await listKeys(filters);
 16 |     return new Response(JSON.stringify({ keys, counts }, null, 2), {
 17 |       status: 200,
 18 |       headers: { 'Content-Type': 'application/json' }
 19 |     });
 20 |   } catch (error) {
 21 |     return handleError('Error listing keys', 500, error);
 22 |   }
 23 | }
 24 | 
 25 | function getFiltersFromHeaders(headers) {
 26 |   return {
 27 |     currentlyConnected: headers.get('X-Filter-Connected') === 'true',
 28 |     createdOn: headers.get('X-Filter-Created-On'),
 29 |     createdInMonth: headers.get('X-Filter-Created-In-Month'),
 30 |     lastSeenOn: headers.get('X-Filter-Last-Seen-On'),
 31 |     lastSeenInMonth: headers.get('X-Filter-Last-Seen-In-Month')
 32 |   };
 33 | }
 34 | 
 35 | async function listKeys(filters) {
 36 |   const keys = {};
 37 |   const counts = {
 38 |     total: 0,
 39 |     currentlyConnected: 0,
 40 |     createdOnDate: 0,
 41 |     createdInMonth: 0,
 42 |     lastSeenOnDate: 0,
 43 |     lastSeenInMonth: 0
 44 |   };
 45 |   let cursor = undefined;
 46 |   let done = false;
 47 | 
 48 |   while (!done) {
 49 |     try {
 50 |       const listResult = await ACCESS_KEYS_NAMESPACE.list({ cursor });
 51 |       for (const key of listResult.keys) {
 52 |         await processKey(key, keys, counts, filters);
 53 |       }
 54 |       cursor = listResult.cursor;
 55 |       done = listResult.list_complete;
 56 |     } catch (error) {
 57 |       logError('Error listing keys:', error);
 58 |       throw new Error(`Failed to list keys: ${error.message}`);
 59 |     }
 60 |   }
 61 | 
 62 |   return { keys, counts };
 63 | }
 64 | 
 65 | async function processKey(key, keys, counts, filters) {
 66 |   try {
 67 |     const value = await ACCESS_KEYS_NAMESPACE.get(key.name);
 68 |     const keyData = JSON.parse(value);
 69 |     counts.total++;
 70 | 
 71 |     if (applyFilters(keyData, filters)) {
 72 |       keys[key.name] = keyData;
 73 |       updateCounts(keyData, counts);
 74 |     }
 75 |   } catch (error) {
 76 |     logError(`Error processing key ${key.name}:`, error);
 77 |     keys[key.name] = { error: `Failed to parse: ${error.message}` };
 78 |   }
 79 | }
 80 | 
 81 | function applyFilters(keyData, filters) {
 82 |   if (filters.currentlyConnected && !keyData.currentlyConnected) return false;
 83 |   if (filters.createdOn && !isOnDate(keyData.creationTime, filters.createdOn)) return false;
 84 |   if (filters.createdInMonth && !isInMonth(keyData.creationTime, filters.createdInMonth)) return false;
 85 |   if (filters.lastSeenOn && !isOnDate(keyData.lastSeen, filters.lastSeenOn)) return false;
 86 |   if (filters.lastSeenInMonth && !isInMonth(keyData.lastSeen, filters.lastSeenInMonth)) return false;
 87 |   return true;
 88 | }
 89 | 
 90 | function updateCounts(keyData, counts) {
 91 |   if (keyData.currentlyConnected) counts.currentlyConnected++;
 92 |   // Add other count updates as needed
 93 | }
 94 | 
 95 | function isOnDate(timestamp, targetDate) {
 96 |   if (!timestamp) return false;
 97 |   const date = new Date(timestamp);
 98 |   const target = new Date(targetDate);
 99 |   return date.toDateString() === target.toDateString();
100 | }
101 | 
102 | function isInMonth(timestamp, targetMonth) {
103 |   if (!timestamp) return false;
104 |   const date = new Date(timestamp);
105 |   const [year, month] = targetMonth.split('-');
106 |   return date.getFullYear() === parseInt(year) && date.getMonth() === parseInt(month) - 1;
107 | }


--------------------------------------------------------------------------------
/wrangler-example.toml:
--------------------------------------------------------------------------------
 1 | #:schema node_modules/wrangler/config-schema.json
 2 | name = "freesocks-control-plane"
 3 | main = "src/index.js"
 4 | compatibility_date = "2024-06-05"
 5 | compatibility_flags = ["nodejs_compat"]
 6 | 
 7 | routes = [
 8 | 	{ pattern = "freesocks.org/get", zone_name = "freesocks.org" },
 9 |   { pattern = "freesocks.org/delete", zone_name = "freesocks.org" },
10 |   { pattern = "freesocks.org/update", zone_name = "freesocks.org" },
11 |   { pattern = "freesocks.org/list", zone_name = "freesocks.org" }
12 | ]
13 | 
14 | ### Cloudflare KV namespace bindings
15 | kv_namespaces = [
16 |   { binding = "FREESOCKS_OUTLINE_API_ENDPOINTS", id = "ID_HERE" },
17 |   { binding = "FREESOCKS_OUTLINE_ACCESS_KEYS", id = "ID_HERE" },
18 |   { binding = "FREESOCKS_PROM_API_ENDPOINTS", id = "ID_HERE" },
19 |   { binding = "FREESOCKS_STATE_KV", id = "ID_HERE" }
20 | ]
21 | 
22 | [triggers]
23 | crons = ["* * * * *"]
24 | 
25 | ### Secrets - manage these with `wrangler secret put <SECRET_NAME>`
26 | # [secrets]
27 | # TURNSTILE_SECRET_KEY = ""
28 | # TURNSTILE_SITE_KEY = ""
29 | # SECRET_AUTH_TOKEN = ""
30 | # VAR_CF_ACCESS_CLIENT_ID = ""
31 | # VAR_CF_ACCESS_CLIENT_SECRET = ""
32 | # S3_PROVIDER_1_ACCESS_KEY_ID = ""
33 | # S3_PROVIDER_1_SECRET_ACCESS_KEY = ""
34 | # S3_PROVIDER_2_ACCESS_KEY_ID = ""
35 | # S3_PROVIDER_2_SECRET_ACCESS_KEY = ""
36 | 
37 | [vars]
38 | 
39 | ### Environment variables for the GET Worker
40 | #TURNSTILE_SECRET_KEY = "" # Cloudflare Turnstile secret key, manage with `wrangler secret` https://developers.cloudflare.com/workers/wrangler/commands/#secret
41 | #TURNSTILE_SITE_KEY = "" # Cloudflare Turnstile site key, manage with `wrangler secret` https://developers.cloudflare.com/workers/wrangler/commands/#secret
42 | VAR_EXPIRATION_DAYS = "90" # Set the expiration period in days
43 | VAR_PREFIX_DISGUISE = "&prefix=%16%03%01%00%C2%A8%01%01" # Custom text to append after the access URL
44 | VAR_WEIGHT_LATENCY = "0.8" # Weight for latency in the score calculation
45 | VAR_WEIGHT_ACCESS_KEY_COUNT = "0.2" # Weight for access key count in the score calculation
46 | VAR_API_ENDPOINT_TIMEOUT = "5000" # Timeout duration for API endpoint requests (in milliseconds)
47 | 
48 | ### Environment variables for the DELETE Worker
49 | #SECRET_AUTH_TOKEN = "" # Set a random auth token, manage with `wrangler secret` https://developers.cloudflare.com/workers/wrangler/commands/#secret
50 | #VAR_CF_ACCESS_CLIENT_ID = "" # Cloudflare Access Service Token details, manage with `wrangler secret` https://developers.cloudflare.com/workers/wrangler/commands/#secret
51 | #VAR_CF_ACCESS_CLIENT_SECRET = "" # Cloudflare Access Service Token details, manage with `wrangler secret` https://developers.cloudflare.com/workers/wrangler/commands/#secret
52 | VAR_PROM_QUERY_TIME_RANGE = "90d" # delete keys that have not been used for X number of days
53 | 
54 | ### Environment variables for the UPDATE Worker
55 | VAR_MAX_KEYS_PER_RUN = "5000" # Cursor-based pagination - how many keys will be processed
56 | VAR_MINIMUM_BYTES_THRESHOLD = "1000" # Minimum number of bytes transferred to consider a key active
57 | VAR_MAX_RETRIES = "2" # Maximum number of retry attempts for operations
58 | VAR_RETRY_DELAY = "1000" # Delay in milliseconds between retry attempts
59 | 
60 | ### WebSocket configuration variables
61 | VAR_WEBSOCKET_ENABLED = "false" # Set to "true" to enable WebSocket support for access keys
62 | # Note: WEBSOCKET_DOMAIN is now read from KV namespace per server (in endpoint JSON data)
63 | VAR_WEBSOCKET_TCP_PATH = "/tcp" # Path for TCP over WebSocket
64 | VAR_WEBSOCKET_UDP_PATH = "/udp" # Path for UDP over WebSocket
65 | VAR_WEBSOCKET_TLS = "true" # Use WSS (true) or WS (false)
66 | 
67 | ### S3 storage configuration
68 | VAR_S3_PROVIDERS_ENABLED = "false" # Set to "true" to enable S3 storage for WebSocket keys
69 | VAR_S3_PROVIDER_COUNT = "0" # Number of S3 providers configured
70 | VAR_S3_UPLOAD_MAX_RETRIES = "3" # Max retries for S3 uploads
71 | 
72 | ### S3 Provider 1 Example (Cloudflare R2)
73 | # VAR_S3_PROVIDER_1_NAME = "r2"
74 | # VAR_S3_PROVIDER_1_ENDPOINT = "https://account.r2.cloudflarestorage.com"
75 | # VAR_S3_PROVIDER_1_BUCKET = "freesocks-keys"
76 | # VAR_S3_PROVIDER_1_PUBLIC_URL = "https://freesocks-keys.account.r2.cloudflarestorage.com"
77 | # VAR_S3_PROVIDER_1_REGION = "auto"
78 | # S3_PROVIDER_1_ACCESS_KEY_ID = "" # Manage with `wrangler secret`
79 | # S3_PROVIDER_1_SECRET_ACCESS_KEY = "" # Manage with `wrangler secret`
80 | 
81 | ### S3 Provider 2 Example (Backblaze B2)
82 | # VAR_S3_PROVIDER_2_NAME = "backblaze"
83 | # VAR_S3_PROVIDER_2_ENDPOINT = "https://s3.us-west-002.backblazeb2.com"
84 | # VAR_S3_PROVIDER_2_BUCKET = "freesocks-keys"
85 | # VAR_S3_PROVIDER_2_PUBLIC_URL = "https://f002.backblazeb2.com/file/freesocks-keys"
86 | # VAR_S3_PROVIDER_2_REGION = "us-west-002"
87 | # S3_PROVIDER_2_ACCESS_KEY_ID = "" # Manage with `wrangler secret`
88 | # S3_PROVIDER_2_SECRET_ACCESS_KEY = "" # Manage with `wrangler secret`
89 | 
90 | ### Delete operation configuration
91 | VAR_DELETE_DRY_RUN = "true" # Default to dry run mode for safety
92 | VAR_DELETE_S3_OBJECTS = "false" # Set to "true" to delete S3 objects when keys are deleted


--------------------------------------------------------------------------------
/src/handlers/delete.js:
--------------------------------------------------------------------------------
  1 | import {
  2 |   AUTH_TOKEN,
  3 |   ACCESS_KEYS_NAMESPACE,
  4 |   API_ENDPOINTS_NAMESPACE,
  5 |   EXPIRATION_DAYS,
  6 |   MAX_RETRIES,
  7 |   RETRY_DELAY,
  8 |   STATE_NAMESPACE,
  9 |   MAX_KEYS_PER_RUN,
 10 |   DELETE_DRY_RUN,
 11 |   DELETE_S3_OBJECTS
 12 | } from '../config/constants.js';
 13 | import { verifyAuth } from '../utils/authentication.js';
 14 | import { handleError, logError, logInfo } from '../utils/errorHandling.js';
 15 | import { parseS3Providers, deleteFromMultipleS3 } from '../utils/s3Storage.js';
 16 | 
 17 | const DELETE_CURSOR_KEY = 'delete_script_cursor';
 18 | 
 19 | async function retry(fn, maxRetries = MAX_RETRIES, delay = RETRY_DELAY) {
 20 |   let lastError;
 21 |   for (let i = 0; i < maxRetries; i++) {
 22 |     try {
 23 |       return await fn();
 24 |     } catch (error) {
 25 |       lastError = error;
 26 |       await new Promise(resolve => setTimeout(resolve, delay));
 27 |     }
 28 |   }
 29 |   throw lastError;
 30 | }
 31 | 
 32 | export async function handleRequest(request, isCronTriggered, env) {
 33 |   logInfo(`handleRequest triggered, isCronTriggered: ${isCronTriggered}`);
 34 | 
 35 |   // Default to dry run mode unless explicitly disabled
 36 |   const isDryRun = request ? 
 37 |     (request.headers.get('X-Dry-Run') !== 'false') : 
 38 |     DELETE_DRY_RUN;
 39 |   
 40 |   const targetServer = request && request.headers.get('X-Target-Server');
 41 |   const targetKey = request && request.headers.get('X-Target-Key');
 42 |   
 43 |   // Parse S3 providers for deletion
 44 |   const s3Providers = DELETE_S3_OBJECTS ? parseS3Providers(env) : [];
 45 | 
 46 |   if (!isCronTriggered) {
 47 |     const isAuthorized = await verifyAuth(request, AUTH_TOKEN);
 48 |     if (!isAuthorized) {
 49 |       return handleError('Unauthorized', 401);
 50 |     }
 51 |   }
 52 | 
 53 |   try {
 54 |     let deleteResults;
 55 |     if (targetKey) {
 56 |       deleteResults = await processKeys([targetKey], isDryRun, targetServer, s3Providers);
 57 |     } else if (targetServer) {
 58 |       deleteResults = await processKeysForServer(targetServer, isDryRun, s3Providers);
 59 |     } else {
 60 |       const startCursor = await retry(() => STATE_NAMESPACE.get(DELETE_CURSOR_KEY));
 61 |       deleteResults = await processAllKeys(isDryRun, startCursor, s3Providers);
 62 |       
 63 |       if (!isDryRun && deleteResults.nextCursor) {
 64 |         await retry(() => STATE_NAMESPACE.put(DELETE_CURSOR_KEY, deleteResults.nextCursor));
 65 |       } else if (!isDryRun && !deleteResults.nextCursor) {
 66 |         await retry(() => STATE_NAMESPACE.delete(DELETE_CURSOR_KEY));
 67 |       }
 68 |     }
 69 | 
 70 |     deleteResults.isDryRun = isDryRun;
 71 |     deleteResults.targetServer = targetServer || null;
 72 |     deleteResults.targetKey = targetKey || null;
 73 |     deleteResults.expirationDays = EXPIRATION_DAYS;
 74 | 
 75 |     return new Response(JSON.stringify(deleteResults, null, 2), {
 76 |       status: 200,
 77 |       headers: { 'Content-Type': 'application/json' }
 78 |     });
 79 |   } catch (error) {
 80 |     return handleError('Error deleting access keys', 500, error);
 81 |   }
 82 | }
 83 | 
 84 | async function processKeys(keys, isDryRun, targetServer, s3Providers) {
 85 |   const deleteResults = {
 86 |     processedKeys: [],
 87 |     errors: []
 88 |   };
 89 | 
 90 |   for (const key of keys) {
 91 |     try {
 92 |       if (targetServer && !key.startsWith(`${targetServer}-key-`)) {
 93 |         deleteResults.errors.push(`Key ${key} does not match target server ${targetServer}`);
 94 |         continue;
 95 |       }
 96 | 
 97 |       const keyData = await retry(() => ACCESS_KEYS_NAMESPACE.get(key));
 98 |       if (!keyData) {
 99 |         deleteResults.errors.push(`Key not found: ${key}`);
100 |         continue;
101 |       }
102 | 
103 |       await processKeyForDeletion(key, JSON.parse(keyData), isDryRun, deleteResults, s3Providers);
104 |     } catch (error) {
105 |       logError(`Error processing key ${key}:`, error);
106 |       deleteResults.errors.push(`Error processing key ${key}: ${error.message}`);
107 |     }
108 |   }
109 | 
110 |   return deleteResults;
111 | }
112 | 
113 | async function processKeysForServer(targetServer, isDryRun, s3Providers) {
114 |   const deleteResults = {
115 |     processedKeys: [],
116 |     errors: [],
117 |     nextCursor: null
118 |   };
119 | 
120 |   let cursor = null;
121 |   let processedCount = 0;
122 | 
123 |   do {
124 |     const listResult = await retry(() => ACCESS_KEYS_NAMESPACE.list({ prefix: `${targetServer}-key-`, cursor, limit: Math.min(MAX_KEYS_PER_RUN - processedCount, 1000) }));
125 | 
126 |     for (const key of listResult.keys) {
127 |       try {
128 |         const keyData = JSON.parse(await ACCESS_KEYS_NAMESPACE.get(key.name));
129 |         await processKeyForDeletion(key.name, keyData, isDryRun, deleteResults, s3Providers);
130 |         processedCount++;
131 |       } catch (error) {
132 |         logError(`Error processing key ${key.name}:`, error);
133 |         deleteResults.errors.push(`Error processing key ${key.name}: ${error.message}`);
134 |       }
135 | 
136 |       if (processedCount >= MAX_KEYS_PER_RUN) {
137 |         deleteResults.nextCursor = `${targetServer}:${listResult.cursor}`;
138 |         return deleteResults;
139 |       }
140 |     }
141 | 
142 |     cursor = listResult.cursor;
143 |   } while (cursor);
144 | 
145 |   return deleteResults;
146 | }
147 | 
148 | async function processAllKeys(isDryRun, startCursor, s3Providers) {
149 |   const deleteResults = {
150 |     processedKeys: [],
151 |     errors: [],
152 |     nextCursor: null
153 |   };
154 | 
155 |   let globalKeyCount = 0;
156 |   const hostnames = await retry(() => API_ENDPOINTS_NAMESPACE.list());
157 |   let startHostname = null;
158 |   let currentCursor = null;
159 | 
160 |   if (startCursor) {
161 |     [startHostname, currentCursor] = startCursor.split(':');
162 |   }
163 | 
164 |   for (const hostname of hostnames.keys) {
165 |     if (startHostname && hostname.name !== startHostname) continue;
166 |     startHostname = null;
167 | 
168 |     try {
169 |       const { processedKeys, nextCursor } = await processKeysForServer(hostname.name, isDryRun, s3Providers);
170 |       deleteResults.processedKeys.push(...processedKeys);
171 |       deleteResults.errors.push(...processedKeys.errors);
172 |       
173 |       globalKeyCount += processedKeys.length;
174 |       if (globalKeyCount >= MAX_KEYS_PER_RUN) {
175 |         deleteResults.nextCursor = `${hostname.name}:${nextCursor}`;
176 |         break;
177 |       }
178 |       currentCursor = null;
179 |     } catch (error) {
180 |       logError(`Error processing hostname ${hostname.name}:`, error);
181 |       deleteResults.errors.push(`Error processing hostname ${hostname.name}: ${error.message}`);
182 |     }
183 |   }
184 | 
185 |   return deleteResults;
186 | }
187 | 
188 | async function processKeyForDeletion(keyName, keyData, isDryRun, deleteResults, s3Providers) {
189 |   const now = new Date();
190 |   const lastSeen = new Date(keyData.lastSeen);
191 |   const daysSinceLastSeen = (now - lastSeen) / (1000 * 60 * 60 * 24);
192 | 
193 |   const keyInfo = {
194 |     key: keyName,
195 |     lastSeen: keyData.lastSeen,
196 |     daysSinceLastSeen: daysSinceLastSeen.toFixed(2),
197 |     currentlyConnected: keyData.currentlyConnected,
198 |     expirationDays: EXPIRATION_DAYS,
199 |     creationTime: keyData.creationTime,
200 |     deletionTime: keyData.deletionTime,
201 |     isWebSocket: keyData.isWebSocket || false,
202 |     s3Paths: keyData.s3Paths || []
203 |   };
204 | 
205 |   const shouldDelete = daysSinceLastSeen > EXPIRATION_DAYS && !keyData.currentlyConnected;
206 | 
207 |   if (shouldDelete) {
208 |     keyInfo.status = isDryRun ? 'Would delete' : 'Deleted';
209 |     keyInfo.reason = `Last seen ${daysSinceLastSeen.toFixed(2)} days ago (> ${EXPIRATION_DAYS} days), not currently connected`;
210 | 
211 |     if (!isDryRun) {
212 |       try {
213 |         const [hostname, accessKey] = keyName.split('-key-');
214 |         const endpointDataStr = await retry(() => API_ENDPOINTS_NAMESPACE.get(hostname));
215 | 
216 |         if (!endpointDataStr) {
217 |           throw new Error(`API endpoint not found for hostname: ${hostname}`);
218 |         }
219 |         
220 |         let apiEndpointUrl;
221 |         try {
222 |           const endpointData = JSON.parse(endpointDataStr);
223 |           apiEndpointUrl = endpointData.apiUrl;
224 |         } catch (e) {
225 |           // Backward compatibility
226 |           apiEndpointUrl = endpointDataStr;
227 |         }
228 | 
229 |         const deleteResult = await sendDeleteRequest(`${apiEndpointUrl}/access-keys/${accessKey}`);
230 |         
231 |         if (deleteResult.success) {
232 |           // Delete S3 objects if configured and present
233 |           if (DELETE_S3_OBJECTS && keyData.s3Paths && keyData.s3Paths.length > 0 && s3Providers.length > 0) {
234 |             try {
235 |               const s3DeleteSuccess = await deleteFromMultipleS3(s3Providers, keyData.s3Paths);
236 |               keyInfo.s3DeleteStatus = s3DeleteSuccess ? 'Deleted' : 'Partial failure';
237 |               logInfo(`S3 deletion for key ${keyName}: ${keyInfo.s3DeleteStatus}`);
238 |             } catch (s3Error) {
239 |               logError(`S3 deletion error for key ${keyName}:`, s3Error);
240 |               keyInfo.s3DeleteStatus = 'Failed';
241 |               keyInfo.s3DeleteError = s3Error.message;
242 |             }
243 |           } else if (keyData.s3Paths && keyData.s3Paths.length > 0) {
244 |             keyInfo.s3DeleteStatus = isDryRun ? 'Would delete' : 'Skipped (S3 deletion disabled)';
245 |           }
246 |           
247 |           keyData.deletionTime = now.toISOString();
248 |           keyData.currentlyConnected = null;
249 |           await retry(() => ACCESS_KEYS_NAMESPACE.put(keyName, JSON.stringify(keyData)));
250 |           keyInfo.deletionTime = keyData.deletionTime;
251 |           keyInfo.currentlyConnected = keyData.currentlyConnected;
252 |         } else {
253 |           throw new Error(`Failed to delete key: ${deleteResult.error}`);
254 |         }
255 |       } catch (error) {
256 |         logError(`Error deleting key ${keyName}:`, error);
257 |         keyInfo.status = 'Error';
258 |         keyInfo.error = error.message;
259 |       }
260 |     }
261 |   } else {
262 |     keyInfo.status = 'Not deleted';
263 |     keyInfo.reason = keyData.currentlyConnected 
264 |       ? 'Currently connected' 
265 |       : `Last seen ${daysSinceLastSeen.toFixed(2)} days ago (<= ${EXPIRATION_DAYS} days)`;
266 |   }
267 | 
268 |   deleteResults.processedKeys.push(keyInfo);
269 | }
270 | 
271 | async function sendDeleteRequest(url) {
272 |   try {
273 |     logInfo(`Sending DELETE request to: ${url}`);
274 |     const response = await fetch(url, { method: 'DELETE' });
275 |     if (!response.ok) {
276 |       const responseBody = await response.text();
277 |       logError(`Failed to delete key. Status: ${response.status}, StatusText: ${response.statusText}`);
278 |       logError(`Response body: ${responseBody}`);
279 |       return { success: false, error: `Status: ${response.status}, Response: ${responseBody}` };
280 |     }
281 |     return { success: true };
282 |   } catch (error) {
283 |     logError(`Error in sendDeleteRequest:`, error);
284 |     return { success: false, error: error.message };
285 |   }
286 | }


--------------------------------------------------------------------------------
/src/handlers/update.js:
--------------------------------------------------------------------------------
  1 | import {
  2 |   AUTH_TOKEN,
  3 |   ACCESS_KEYS_NAMESPACE,
  4 |   API_ENDPOINTS_NAMESPACE,
  5 |   CF_ACCESS_CLIENT_ID,
  6 |   CF_ACCESS_CLIENT_SECRET,
  7 |   MAX_KEYS_PER_RUN,
  8 |   STATE_NAMESPACE,
  9 |   MAX_RETRIES,
 10 |   RETRY_DELAY
 11 | } from '../config/constants.js';
 12 | import { verifyAuth } from '../utils/authentication.js';
 13 | import { handleError, logError, logInfo } from '../utils/errorHandling.js';
 14 | import { queryPrometheus } from '../utils/prometheusQueries.js';
 15 | 
 16 | const UPDATE_CURSOR_KEY = 'update_script_cursor';
 17 | 
 18 | async function retry(fn, maxRetries = MAX_RETRIES, delay = RETRY_DELAY) {
 19 |   let lastError;
 20 |   for (let i = 0; i < maxRetries; i++) {
 21 |     try {
 22 |       return await fn();
 23 |     } catch (error) {
 24 |       lastError = error;
 25 |       await new Promise(resolve => setTimeout(resolve, delay));
 26 |     }
 27 |   }
 28 |   throw lastError;
 29 | }
 30 | 
 31 | export async function handleRequest(request, isCronTriggered) {
 32 |   logInfo(`handleRequest triggered, isCronTriggered: ${isCronTriggered}`);
 33 | 
 34 |   const isDryRun = request && request.headers.get('X-Dry-Run') === 'true';
 35 |   const targetKey = request && request.headers.get('X-Target-Key');
 36 |   const isDebug = request && request.headers.get('X-Debug') === 'true';
 37 | 
 38 |   if (!isCronTriggered) {
 39 |     const isAuthorized = await verifyAuth(request, AUTH_TOKEN);
 40 |     if (!isAuthorized) {
 41 |       return handleError('Unauthorized', 401);
 42 |     }
 43 |   }
 44 | 
 45 |   try {
 46 |     let updateResults;
 47 |     if (targetKey) {
 48 |       updateResults = await updateTargetKey(targetKey, isDryRun, isDebug);
 49 |     } else {
 50 |       const startCursor = await retry(() => STATE_NAMESPACE.get(UPDATE_CURSOR_KEY));
 51 |       updateResults = await updateAccessKeys(isDryRun, startCursor, isDebug);
 52 |       
 53 |       if (!isDryRun && updateResults.nextCursor) {
 54 |         await retry(() => STATE_NAMESPACE.put(UPDATE_CURSOR_KEY, updateResults.nextCursor));
 55 |       } else if (!isDryRun && !updateResults.nextCursor) {
 56 |         await retry(() => STATE_NAMESPACE.delete(UPDATE_CURSOR_KEY));
 57 |       }
 58 |     }
 59 | 
 60 |     updateResults.isDryRun = isDryRun;
 61 |     updateResults.targetKey = targetKey || null;
 62 |     updateResults.isDebug = isDebug;
 63 |     
 64 |     return new Response(JSON.stringify(updateResults, null, 2), { 
 65 |       status: 200,
 66 |       headers: { 'Content-Type': 'application/json' }
 67 |     });
 68 |   } catch (error) {
 69 |     return handleError('Error updating access keys', 500, error);
 70 |   }
 71 | }
 72 | 
 73 | async function updateTargetKey(targetKey, isDryRun, isDebug) {
 74 |   const updateResults = {
 75 |     updatedKeys: [],
 76 |     errors: [],
 77 |     debugInfo: isDebug ? {} : undefined
 78 |   };
 79 | 
 80 |   try {
 81 |     const [hostname] = targetKey.split('-key-');
 82 |     const endpointDataStr = await retry(() => API_ENDPOINTS_NAMESPACE.get(hostname));
 83 |     
 84 |     if (!endpointDataStr) {
 85 |       updateResults.errors.push(`Endpoint not found for hostname: ${hostname}`);
 86 |       return updateResults;
 87 |     }
 88 |     
 89 |     let promApiEndpoint;
 90 |     try {
 91 |       const endpointData = JSON.parse(endpointDataStr);
 92 |       promApiEndpoint = endpointData.prometheusUrl;
 93 |     } catch (e) {
 94 |       updateResults.errors.push(`Invalid endpoint data for hostname: ${hostname}`);
 95 |       return updateResults;
 96 |     }
 97 |     
 98 |     logInfo(`Processing target key: ${targetKey}, Prometheus endpoint: ${promApiEndpoint}`);
 99 |     
100 |     const activeKeysResult = await queryActiveKeys(promApiEndpoint, targetKey);
101 |     
102 |     if (!activeKeysResult.success) {
103 |       updateResults.errors.push(`Error querying active keys for ${hostname}: ${activeKeysResult.error}`);
104 |       return updateResults;
105 |     }
106 | 
107 |     const activeKeys = activeKeysResult.data;
108 |     if (isDebug) {
109 |       updateResults.debugInfo.prometheusQuery = activeKeysResult.debugInfo;
110 |     }
111 |     await processKey(targetKey, activeKeys, isDryRun, updateResults, isDebug);
112 |   } catch (error) {
113 |     logError(`Error processing target key ${targetKey}:`, error);
114 |     updateResults.errors.push(`Error processing target key ${targetKey}: ${error.message}`);
115 |   }
116 | 
117 |   return updateResults;
118 | }
119 | 
120 | async function updateAccessKeys(isDryRun, startCursor, isDebug) {
121 |   const updateResults = {
122 |     updatedKeys: [],
123 |     errors: [],
124 |     nextCursor: null,
125 |     debugInfo: isDebug ? {} : undefined
126 |   };
127 | 
128 |   let globalKeyCount = 0;
129 |   const hostnames = await retry(() => API_ENDPOINTS_NAMESPACE.list());
130 |   let startHostname = null;
131 |   let currentCursor = null;
132 | 
133 |   if (startCursor) {
134 |     [startHostname, currentCursor] = startCursor.split(':');
135 |   }
136 | 
137 |   for (const hostname of hostnames.keys) {
138 |     if (startHostname && hostname.name !== startHostname) continue;
139 |     startHostname = null;
140 | 
141 |     try {
142 |       const endpointDataStr = await retry(() => API_ENDPOINTS_NAMESPACE.get(hostname.name));
143 |       
144 |       if (!endpointDataStr) {
145 |         updateResults.errors.push(`Endpoint not found for hostname: ${hostname.name}`);
146 |         continue;
147 |       }
148 |       
149 |       let promApiEndpoint;
150 |       try {
151 |         const endpointData = JSON.parse(endpointDataStr);
152 |         promApiEndpoint = endpointData.prometheusUrl;
153 |       } catch (e) {
154 |         updateResults.errors.push(`Invalid endpoint data for hostname: ${hostname.name}`);
155 |         continue;
156 |       }
157 |       
158 |       logInfo(`Processing hostname: ${hostname.name}, Prometheus endpoint: ${promApiEndpoint}`);
159 |       const activeKeysResult = await queryActiveKeys(promApiEndpoint);
160 |       
161 |       if (!activeKeysResult.success) {
162 |         updateResults.errors.push(`Error querying active keys for ${hostname.name}: ${activeKeysResult.error}`);
163 |         continue;
164 |       }
165 | 
166 |       const activeKeys = activeKeysResult.data;
167 |       const { processedKeys, nextCursor } = await processKeysForHostname(hostname.name, activeKeys, isDryRun, updateResults, MAX_KEYS_PER_RUN - globalKeyCount, currentCursor, isDebug);
168 |       
169 |       globalKeyCount += processedKeys;
170 |       if (globalKeyCount >= MAX_KEYS_PER_RUN) {
171 |         updateResults.nextCursor = `${hostname.name}:${nextCursor}`;
172 |         break;
173 |       }
174 |       currentCursor = null;
175 |     } catch (error) {
176 |       logError(`Error processing hostname ${hostname.name}:`, error);
177 |       updateResults.errors.push(`Error processing hostname ${hostname.name}: ${error.message}`);
178 |     }
179 |   }
180 | 
181 |   return updateResults;
182 | }
183 | 
184 | async function processKeysForHostname(hostname, activeKeys, isDryRun, updateResults, remainingKeys, startCursor, isDebug) {
185 |   let cursor = startCursor;
186 |   let processedKeys = 0;
187 | 
188 |   do {
189 |     const listResult = await retry(() => ACCESS_KEYS_NAMESPACE.list({ prefix: `${hostname}-key-`, cursor, limit: Math.min(remainingKeys, 1000) }));
190 |     
191 |     for (const key of listResult.keys) {
192 |       await processKey(key.name, activeKeys, isDryRun, updateResults, isDebug);
193 |       processedKeys++;
194 |       remainingKeys--;
195 |       if (remainingKeys <= 0) break;
196 |     }
197 | 
198 |     cursor = listResult.cursor;
199 |   } while (cursor && remainingKeys > 0);
200 | 
201 |   return { processedKeys, nextCursor: cursor };
202 | }
203 | 
204 | async function processKey(key, activeKeys, isDryRun, updateResults, isDebug) {
205 |   try {
206 |     const keyData = await retry(() => ACCESS_KEYS_NAMESPACE.get(key).then(JSON.parse));
207 |     
208 |     // Populate missing fields
209 |     const updatedKeyData = {
210 |       ...keyData,
211 |       deletionTime: keyData.deletionTime ?? null,
212 |       lastSeen: keyData.lastSeen ?? null,
213 |       currentlyConnected: keyData.currentlyConnected ?? null
214 |     };
215 | 
216 |     // Check if we need to update the key data due to missing fields
217 |     const needsUpdate = JSON.stringify(keyData) !== JSON.stringify(updatedKeyData);
218 | 
219 |     if (needsUpdate) {
220 |       if (isDryRun) {
221 |         updateResults.updatedKeys.push({
222 |           key: key,
223 |           before: keyData,
224 |           after: updatedKeyData,
225 |           changes: {
226 |             deletionTime: keyData.deletionTime === undefined ? 'added' : 'unchanged',
227 |             lastSeen: keyData.lastSeen === undefined ? 'added' : 'unchanged',
228 |             currentlyConnected: keyData.currentlyConnected === undefined ? 'added' : 'unchanged'
229 |           }
230 |         });
231 |       } else {
232 |         await retry(() => ACCESS_KEYS_NAMESPACE.put(key, JSON.stringify(updatedKeyData)));
233 |         updateResults.updatedKeys.push({
234 |           key: key,
235 |           changes: {
236 |             deletionTime: keyData.deletionTime === undefined ? 'added' : 'unchanged',
237 |             lastSeen: keyData.lastSeen === undefined ? 'added' : 'unchanged',
238 |             currentlyConnected: keyData.currentlyConnected === undefined ? 'added' : 'unchanged'
239 |           }
240 |         });
241 |       }
242 |       logInfo(`Updated key ${key} with missing fields`);
243 |       return; // Skip Prometheus comparison for this run
244 |     }
245 | 
246 |     if (updatedKeyData.deletionTime) return; // Skip deleted keys
247 | 
248 |     const accessKeyId = key.split('-').pop(); // This correctly extracts the key ID
249 |     const isActive = accessKeyId in activeKeys && activeKeys[accessKeyId].totalBytes > 0;
250 |     const now = new Date().toISOString();
251 | 
252 |     const finalKeyData = {
253 |       ...updatedKeyData,
254 |       currentlyConnected: isActive,
255 |       lastSeen: isActive ? activeKeys[accessKeyId].lastSeen : updatedKeyData.lastSeen
256 |     };
257 | 
258 |     let hasChanges = isActive || updatedKeyData.currentlyConnected !== isActive || (isActive && updatedKeyData.lastSeen !== finalKeyData.lastSeen);
259 | 
260 |     const keyUpdateInfo = {
261 |       key: key,
262 |       before: updatedKeyData,
263 |       after: finalKeyData,
264 |       changes: {
265 |         currentlyConnected: isActive !== updatedKeyData.currentlyConnected ? isActive : 'unchanged',
266 |         lastSeen: isActive ? finalKeyData.lastSeen : 'unchanged'
267 |       }
268 |     };
269 | 
270 |     if (isDebug) {
271 |       keyUpdateInfo.debugInfo = {
272 |         accessKeyId,
273 |         isActiveInPrometheusData: isActive,
274 |         activeKeysData: activeKeys[accessKeyId]
275 |       };
276 |     }
277 | 
278 |     if (hasChanges) {
279 |       if (isDryRun) {
280 |         updateResults.updatedKeys.push(keyUpdateInfo);
281 |       } else {
282 |         await retry(() => ACCESS_KEYS_NAMESPACE.put(key, JSON.stringify(finalKeyData)));
283 |         updateResults.updatedKeys.push(keyUpdateInfo);
284 |       }
285 |     }
286 | 
287 |     logInfo(`Processed key ${key}: isActive=${isActive}, lastSeen=${finalKeyData.lastSeen}`);
288 |   } catch (error) {
289 |     logError(`Error processing key ${key}:`, error);
290 |     updateResults.errors.push(`Error processing key ${key}: ${error.message}`);
291 |   }
292 | }
293 | 
294 | async function queryActiveKeys(promApiEndpoint, targetKey = null) {
295 |   const query = `increase(shadowsocks_data_bytes{dir=~"c<p|p>t"}[30m]) > 0`;
296 |   
297 |   try {
298 |     logInfo(`Querying Prometheus for ${promApiEndpoint} with query: ${query}`);
299 |     
300 |     const queryResult = await retry(() => queryPrometheus(promApiEndpoint, query, CF_ACCESS_CLIENT_ID, CF_ACCESS_CLIENT_SECRET));
301 | 
302 |     logInfo(`Raw Prometheus response for ${promApiEndpoint}:`, JSON.stringify(queryResult, null, 2));
303 | 
304 |     if (!queryResult.success) {
305 |       return { success: false, error: `Prometheus query unsuccessful: ${JSON.stringify(queryResult)}` };
306 |     }
307 | 
308 |     if (!queryResult.data || !Array.isArray(queryResult.data)) {
309 |       return { success: false, error: `Unexpected Prometheus response structure: ${JSON.stringify(queryResult)}` };
310 |     }
311 | 
312 |     const activeKeys = {};
313 |     queryResult.data.forEach(item => {
314 |       if (item && item.metric && item.metric.access_key && Array.isArray(item.value) && item.value.length === 2) {
315 |         const accessKey = item.metric.access_key;
316 |         const timestamp = new Date(item.value[0] * 1000).toISOString();
317 |         const bytes = parseFloat(item.value[1]);
318 | 
319 |         if (!activeKeys[accessKey]) {
320 |           activeKeys[accessKey] = {
321 |             totalBytes: 0,
322 |             lastSeen: timestamp
323 |           };
324 |         }
325 |         activeKeys[accessKey].totalBytes += bytes;
326 |         if (timestamp > activeKeys[accessKey].lastSeen) {
327 |           activeKeys[accessKey].lastSeen = timestamp;
328 |         }
329 |       }
330 |     });
331 | 
332 |     logInfo(`Processed active keys for ${promApiEndpoint}:`, JSON.stringify(activeKeys));
333 |     
334 |     const result = { success: true, data: activeKeys };
335 |     
336 |     if (targetKey) {
337 |       const targetAccessKey = targetKey.split('-').pop();
338 |       result.debugInfo = {
339 |         query,
340 |         targetKeyInfo: activeKeys[targetAccessKey] || null,
341 |         rawResponse: queryResult
342 |       };
343 |     }
344 |     
345 |     return result;
346 |   } catch (error) {
347 |     logError(`Error querying Prometheus for ${promApiEndpoint}:`, error);
348 |     return { success: false, error: `Error querying Prometheus: ${error.message}` };
349 |   }
350 | }


--------------------------------------------------------------------------------
/src/utils/s3Storage.js:
--------------------------------------------------------------------------------
  1 | import { logError, logInfo } from './errorHandling.js';
  2 | 
  3 | /**
  4 |  * S3 storage utilities for uploading and managing dynamic access keys
  5 |  */
  6 | 
  7 | /**
  8 |  * Parse S3 provider configuration from environment variables
  9 |  */
 10 | export function parseS3Providers(env) {
 11 |   const providers = [];
 12 |   // In service worker syntax, we need to access globals directly
 13 |   const providerCount = parseInt(globalThis.VAR_S3_PROVIDER_COUNT || '0');
 14 |   
 15 |   logInfo(`parseS3Providers: VAR_S3_PROVIDER_COUNT = ${providerCount}`);
 16 |   
 17 |   for (let i = 1; i <= providerCount; i++) {
 18 |     const name = globalThis[`VAR_S3_PROVIDER_${i}_NAME`];
 19 |     const endpoint = globalThis[`VAR_S3_PROVIDER_${i}_ENDPOINT`];
 20 |     const bucket = globalThis[`VAR_S3_PROVIDER_${i}_BUCKET`];
 21 |     const publicUrl = globalThis[`VAR_S3_PROVIDER_${i}_PUBLIC_URL`];
 22 |     const region = globalThis[`VAR_S3_PROVIDER_${i}_REGION`] || 'us-east-1';
 23 |     // Secrets are accessed the same way as globals
 24 |     const accessKeyId = globalThis[`S3_PROVIDER_${i}_ACCESS_KEY_ID`];
 25 |     const secretAccessKey = globalThis[`S3_PROVIDER_${i}_SECRET_ACCESS_KEY`];
 26 |     
 27 |     if (name && endpoint && bucket && publicUrl && accessKeyId && secretAccessKey) {
 28 |       providers.push({
 29 |         name,
 30 |         endpoint,
 31 |         bucket,
 32 |         publicUrl,
 33 |         region,
 34 |         accessKeyId,
 35 |         secretAccessKey
 36 |       });
 37 |       logInfo(`S3 Provider ${i} configured: ${name} at ${endpoint}`);
 38 |     } else {
 39 |       // Log what's missing for debugging
 40 |       logError(`S3 Provider ${i} incomplete config:`, {
 41 |         name: !!name,
 42 |         endpoint: !!endpoint,
 43 |         bucket: !!bucket,
 44 |         publicUrl: !!publicUrl,
 45 |         accessKeyId: !!accessKeyId,
 46 |         secretAccessKey: !!secretAccessKey
 47 |       });
 48 |       logError(`Provider ${i} values:`, {
 49 |         name: name || 'MISSING',
 50 |         endpoint: endpoint || 'MISSING',
 51 |         bucket: bucket || 'MISSING',
 52 |         publicUrl: publicUrl || 'MISSING',
 53 |         accessKeyId: accessKeyId ? 'SET' : 'MISSING',
 54 |         secretAccessKey: secretAccessKey ? 'SET' : 'MISSING'
 55 |       });
 56 |     }
 57 |   }
 58 |   
 59 |   return providers;
 60 | }
 61 | 
 62 | /**
 63 |  * Generate S3 object path for a key
 64 |  */
 65 | export function generateS3Path(serverName, keyId) {
 66 |   // Generate cryptographically secure random string
 67 |   const randomBytes = new Uint8Array(16);
 68 |   crypto.getRandomValues(randomBytes);
 69 |   const randomString = Array.from(randomBytes)
 70 |     .map(b => b.toString(16).padStart(2, '0'))
 71 |     .join('');
 72 |   
 73 |   return `keys/${serverName}-${randomString}/${keyId}`;
 74 | }
 75 | 
 76 | /**
 77 |  * Extract server name from WebSocket domain
 78 |  * e.g., "clinks-hoot-champed.freesocks.work" -> "clinks-hoot-champed"
 79 |  */
 80 | export function extractServerName(domain) {
 81 |   if (!domain) return 'unknown';
 82 |   const parts = domain.split('.');
 83 |   return parts[0] || 'unknown';
 84 | }
 85 | 
 86 | /**
 87 |  * Create AWS Signature V4 for S3 requests
 88 |  */
 89 | async function createAWSSignature(method, url, headers, credentials) {
 90 |   // Use the datetime from headers to ensure consistency
 91 |   const datetime = headers['x-amz-date'];
 92 |   const date = datetime.substring(0, 8);
 93 |   
 94 |   const parsedUrl = new URL(url);
 95 |   const canonicalUri = parsedUrl.pathname;
 96 |   const canonicalQueryString = parsedUrl.searchParams.toString();
 97 |   
 98 |   // Create canonical headers
 99 |   const signedHeaders = Object.keys(headers)
100 |     .sort()
101 |     .map(k => k.toLowerCase())
102 |     .join(';');
103 |   
104 |   const canonicalHeaders = Object.keys(headers)
105 |     .sort()
106 |     .map(k => `${k.toLowerCase()}:${headers[k].trim()}`)
107 |     .join('\n') + '\n';
108 |   
109 |   // Use the payload hash from headers to ensure consistency
110 |   const payloadHashHex = headers['x-amz-content-sha256'];
111 |   
112 |   // Create canonical request
113 |   const canonicalRequest = [
114 |     method,
115 |     canonicalUri,
116 |     canonicalQueryString,
117 |     canonicalHeaders,
118 |     signedHeaders,
119 |     payloadHashHex
120 |   ].join('\n');
121 |   
122 |   // Create string to sign
123 |   const encoder = new TextEncoder();
124 |   const requestHash = await crypto.subtle.digest('SHA-256', encoder.encode(canonicalRequest));
125 |   const requestHashHex = Array.from(new Uint8Array(requestHash))
126 |     .map(b => b.toString(16).padStart(2, '0'))
127 |     .join('');
128 |   
129 |   const credentialScope = `${date}/${credentials.region}/s3/aws4_request`;
130 |   const stringToSign = [
131 |     'AWS4-HMAC-SHA256',
132 |     datetime,
133 |     credentialScope,
134 |     requestHashHex
135 |   ].join('\n');
136 |   
137 |   // Create signing key
138 |   const kDate = await hmac(`AWS4${credentials.secretAccessKey}`, date);
139 |   const kRegion = await hmac(kDate, credentials.region);
140 |   const kService = await hmac(kRegion, 's3');
141 |   const kSigning = await hmac(kService, 'aws4_request');
142 |   
143 |   // Create signature
144 |   const signature = await hmac(kSigning, stringToSign);
145 |   const signatureHex = Array.from(new Uint8Array(signature))
146 |     .map(b => b.toString(16).padStart(2, '0'))
147 |     .join('');
148 |   
149 |   // Create authorization header
150 |   const authorization = `AWS4-HMAC-SHA256 Credential=${credentials.accessKeyId}/${credentialScope}, SignedHeaders=${signedHeaders}, Signature=${signatureHex}`;
151 |   
152 |   return {
153 |     authorization
154 |   };
155 | }
156 | 
157 | /**
158 |  * HMAC helper function
159 |  */
160 | async function hmac(key, data) {
161 |   const encoder = new TextEncoder();
162 |   const keyData = typeof key === 'string' ? encoder.encode(key) : key;
163 |   const dataArray = encoder.encode(data);
164 |   
165 |   const cryptoKey = await crypto.subtle.importKey(
166 |     'raw',
167 |     keyData,
168 |     { name: 'HMAC', hash: 'SHA-256' },
169 |     false,
170 |     ['sign']
171 |   );
172 |   
173 |   return await crypto.subtle.sign('HMAC', cryptoKey, dataArray);
174 | }
175 | 
176 | /**
177 |  * Upload content to S3 with retry logic
178 |  */
179 | export async function uploadToS3(provider, path, content, maxRetries = 3) {
180 |   const url = `${provider.endpoint}/${provider.bucket}/${path}`;
181 |   logInfo(`Uploading to ${provider.name}: ${url}`);
182 |   
183 |   for (let attempt = 1; attempt <= maxRetries; attempt++) {
184 |     try {
185 |       logInfo(`Upload attempt ${attempt}/${maxRetries} to ${provider.name}`);
186 |       
187 |       // Calculate the payload hash first
188 |       const encoder = new TextEncoder();
189 |       const payloadData = encoder.encode(content);
190 |       const payloadHash = await crypto.subtle.digest('SHA-256', payloadData);
191 |       const payloadHashHex = Array.from(new Uint8Array(payloadHash))
192 |         .map(b => b.toString(16).padStart(2, '0'))
193 |         .join('');
194 |       
195 |       const datetime = new Date().toISOString().replace(/[:-]|\.\d{3}/g, '');
196 |       const headers = {
197 |         'Host': new URL(provider.endpoint).hostname,
198 |         'Content-Type': 'text/plain',
199 |         'x-amz-date': datetime,
200 |         'x-amz-content-sha256': payloadHashHex
201 |       };
202 |       
203 |       const signature = await createAWSSignature(
204 |         'PUT',
205 |         url,
206 |         headers,
207 |         {
208 |           accessKeyId: provider.accessKeyId,
209 |           secretAccessKey: provider.secretAccessKey,
210 |           region: provider.region
211 |         }
212 |       );
213 |       
214 |       headers['Authorization'] = signature.authorization;
215 |       
216 |       const response = await fetch(url, {
217 |         method: 'PUT',
218 |         headers,
219 |         body: content
220 |       });
221 |       
222 |       logInfo(`S3 response status: ${response.status} ${response.statusText}`);
223 |       
224 |       if (response.ok) {
225 |         const publicUrl = `${provider.publicUrl}/${path}`;
226 |         logInfo(`Upload successful to ${provider.name}: ${publicUrl}`);
227 |         return publicUrl;
228 |       }
229 |       
230 |       const responseText = await response.text();
231 |       logError(`S3 upload failed:`, {
232 |         status: response.status,
233 |         statusText: response.statusText,
234 |         body: responseText,
235 |         provider: provider.name,
236 |         url: url
237 |       });
238 |       
239 |       if (response.status < 500 && response.status !== 429) {
240 |         // Don't retry on client errors (except rate limits)
241 |         throw new Error(`S3 upload failed with status ${response.status}: ${responseText}`);
242 |       }
243 |       
244 |       // Log retry attempt
245 |       if (attempt < maxRetries) {
246 |         const delay = Math.min(1000 * Math.pow(2, attempt - 1), 10000);
247 |         logError(`S3 upload attempt ${attempt} failed, retrying in ${delay}ms...`);
248 |         await new Promise(resolve => setTimeout(resolve, delay));
249 |       }
250 |       
251 |     } catch (error) {
252 |       if (attempt === maxRetries) {
253 |         throw error;
254 |       }
255 |       logError(`S3 upload attempt ${attempt} error:`, error);
256 |       const delay = Math.min(1000 * Math.pow(2, attempt - 1), 10000);
257 |       await new Promise(resolve => setTimeout(resolve, delay));
258 |     }
259 |   }
260 |   
261 |   throw new Error(`Failed to upload to S3 after ${maxRetries} attempts`);
262 | }
263 | 
264 | /**
265 |  * Upload content to multiple S3 providers
266 |  */
267 | export async function uploadToMultipleS3(providers, serverName, keyId, content) {
268 |   const path = generateS3Path(serverName, keyId);
269 |   logInfo(`Generated S3 path: ${path}`);
270 |   logInfo(`Uploading to ${providers.length} S3 providers...`);
271 |   
272 |   const uploadPromises = providers.map(provider => 
273 |     uploadToS3(provider, path, content)
274 |       .then(url => ({ success: true, url, provider: provider.name }))
275 |       .catch(error => ({ success: false, error, provider: provider.name }))
276 |   );
277 |   
278 |   const results = await Promise.all(uploadPromises);
279 |   const successfulUploads = results.filter(r => r.success);
280 |   
281 |   if (successfulUploads.length === 0) {
282 |     const errors = results.map(r => `${r.provider}: ${r.error?.message}`).join(', ');
283 |     throw new Error(`All S3 uploads failed: ${errors}`);
284 |   }
285 |   
286 |   // Log partial failures for monitoring
287 |   const failedUploads = results.filter(r => !r.success);
288 |   if (failedUploads.length > 0) {
289 |     logError('Some S3 uploads failed:', failedUploads);
290 |   }
291 |   
292 |   return successfulUploads.map(r => r.url);
293 | }
294 | 
295 | /**
296 |  * Delete object from S3
297 |  */
298 | export async function deleteFromS3(provider, path) {
299 |   const url = `${provider.endpoint}/${provider.bucket}/${path}`;
300 |   
301 |   try {
302 |     // For DELETE, we use empty body hash
303 |     const emptyBodyHash = 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855';
304 |     const datetime = new Date().toISOString().replace(/[:-]|\.\d{3}/g, '');
305 |     
306 |     const headers = {
307 |       'Host': new URL(provider.endpoint).hostname,
308 |       'x-amz-date': datetime,
309 |       'x-amz-content-sha256': emptyBodyHash
310 |     };
311 |     
312 |     const signature = await createAWSSignature(
313 |       'DELETE',
314 |       url,
315 |       headers,
316 |       {
317 |         accessKeyId: provider.accessKeyId,
318 |         secretAccessKey: provider.secretAccessKey,
319 |         region: provider.region
320 |       }
321 |     );
322 |     
323 |     headers['Authorization'] = signature.authorization;
324 |     
325 |     const response = await fetch(url, {
326 |       method: 'DELETE',
327 |       headers
328 |     });
329 |     
330 |     if (!response.ok && response.status !== 404) {
331 |       throw new Error(`S3 delete failed with status ${response.status}`);
332 |     }
333 |     
334 |     return true;
335 |   } catch (error) {
336 |     logError(`Failed to delete from S3:`, error);
337 |     return false;
338 |   }
339 | }
340 | 
341 | /**
342 |  * Test S3 endpoint latency and return the optimal URL
343 |  */
344 | export async function getOptimalS3Url(s3Urls, timeout = 5000) {
345 |   if (s3Urls.length === 0) {
346 |     throw new Error('No S3 URLs provided');
347 |   }
348 |   
349 |   if (s3Urls.length === 1) {
350 |     return s3Urls[0];
351 |   }
352 |   
353 |   logInfo(`Testing latency for ${s3Urls.length} S3 URLs...`);
354 |   const latencyScores = [];
355 |   
356 |   const testPromises = s3Urls.map(async (url) => {
357 |     try {
358 |       const controller = new AbortController();
359 |       const timeoutId = setTimeout(() => controller.abort(), timeout);
360 |       
361 |       const startTime = performance.now();
362 |       // Use HEAD request to test latency without downloading content
363 |       const response = await fetch(url, { 
364 |         method: 'HEAD',
365 |         signal: controller.signal 
366 |       });
367 |       const endTime = performance.now();
368 |       const latency = endTime - startTime;
369 |       
370 |       clearTimeout(timeoutId);
371 |       
372 |       if (response.ok || response.status === 403) {
373 |         // 403 is OK for latency testing - it means the server responded
374 |         latencyScores.push({ url, latency });
375 |         logInfo(`S3 latency test for ${new URL(url).hostname}: ${latency.toFixed(0)}ms`);
376 |       } else {
377 |         logError(`Failed to test S3 latency for ${url}. Status: ${response.status}`);
378 |       }
379 |     } catch (error) {
380 |       if (error.name === 'AbortError') {
381 |         logError(`S3 latency test timed out for ${url}`);
382 |       } else {
383 |         logError(`Error testing S3 latency for ${url}:`, error);
384 |       }
385 |     }
386 |   });
387 |   
388 |   await Promise.all(testPromises);
389 |   
390 |   if (latencyScores.length === 0) {
391 |     // If all latency tests failed, return the first URL as fallback
392 |     logError('All S3 latency tests failed, using first URL as fallback');
393 |     return s3Urls[0];
394 |   }
395 |   
396 |   // Sort by latency (lowest first)
397 |   latencyScores.sort((a, b) => a.latency - b.latency);
398 |   
399 |   logInfo(`Optimal S3 URL selected: ${latencyScores[0].url} (${latencyScores[0].latency.toFixed(0)}ms)`);
400 |   return latencyScores[0].url;
401 | }
402 | 
403 | /**
404 |  * Delete object from multiple S3 providers
405 |  */
406 | export async function deleteFromMultipleS3(providers, s3Urls) {
407 |   const deletePromises = s3Urls.map(async (url) => {
408 |     // Extract provider and path from URL
409 |     const provider = providers.find(p => url.startsWith(p.publicUrl));
410 |     if (!provider) {
411 |       logError(`No provider found for URL: ${url}`);
412 |       return false;
413 |     }
414 |     
415 |     const path = url.replace(provider.publicUrl + '/', '');
416 |     return await deleteFromS3(provider, path);
417 |   });
418 |   
419 |   const results = await Promise.all(deletePromises);
420 |   const successCount = results.filter(r => r).length;
421 |   
422 |   if (successCount < results.length) {
423 |     logError(`Only ${successCount}/${results.length} S3 deletions succeeded`);
424 |   }
425 |   
426 |   return successCount > 0;
427 | }


--------------------------------------------------------------------------------
/src/handlers/get.js:
--------------------------------------------------------------------------------
  1 | import {
  2 |     turnstileSecretKey,
  3 |     turnstileSiteKey,
  4 |     API_ENDPOINTS_NAMESPACE,
  5 |     ACCESS_KEYS_NAMESPACE,
  6 |     EXPIRATION_DAYS,
  7 |     PREFIX_DISGUISE,
  8 |     WEIGHT_LATENCY,
  9 |     WEIGHT_ACCESS_KEY_COUNT,
 10 |     API_ENDPOINT_TIMEOUT,
 11 |     WEBSOCKET_ENABLED,
 12 |     WEBSOCKET_TCP_PATH,
 13 |     WEBSOCKET_UDP_PATH,
 14 |     WEBSOCKET_TLS,
 15 |     S3_PROVIDERS_ENABLED,
 16 |     S3_UPLOAD_MAX_RETRIES
 17 |   } from '../config/constants.js';
 18 |   import { verifyTurnstile } from '../utils/authentication.js';
 19 |   import { handleError, logError, logInfo } from '../utils/errorHandling.js';
 20 |   import { parseS3Providers, uploadToMultipleS3, extractServerName, getOptimalS3Url } from '../utils/s3Storage.js';
 21 |   
 22 |   // Main request handling function
 23 |   export async function handleRequest(request, env) {
 24 |     const requestHostname = new URL(request.url).hostname;
 25 |   
 26 |     if (request.method === "POST") {
 27 |       const isHuman = await validateFormAndTurnstile(request, turnstileSecretKey);
 28 |       if (!isHuman) {
 29 |         return new Response("Cloudflare Turnstile verification failed", { status: 403 });
 30 |       }
 31 |   
 32 |       try {
 33 |         const endpointKey = await getOptimalApiEndpoint(API_ENDPOINTS_NAMESPACE);
 34 |         const endpointDataStr = await API_ENDPOINTS_NAMESPACE.get(endpointKey);
 35 |         
 36 |         if (!endpointDataStr) {
 37 |           return new Response('API endpoint not found', { status: 500 });
 38 |         }
 39 |         
 40 |         let endpointData;
 41 |         try {
 42 |           endpointData = JSON.parse(endpointDataStr);
 43 |         } catch (e) {
 44 |           // Backward compatibility: if it's not JSON, assume it's just the API URL
 45 |           endpointData = { apiUrl: endpointDataStr };
 46 |         }
 47 |         
 48 |         let apiEndpointUrl = endpointData.apiUrl;
 49 |         const websocketDomain = endpointData.websocketDomain || '';
 50 |         
 51 |         if (apiEndpointUrl) {
 52 |           apiEndpointUrl = modifyApiEndpointUrl(apiEndpointUrl, requestHostname);
 53 |         }
 54 |   
 55 |         if (!apiEndpointUrl) {
 56 |           return new Response('API endpoint URL not found', { status: 500 });
 57 |         }
 58 |   
 59 |         const accessKeyData = await createNewAccessKey(apiEndpointUrl, websocketDomain);
 60 |         if (accessKeyData && accessKeyData.id) {
 61 |           const keyId = `${endpointKey}-key-${accessKeyData.id}`;
 62 |           const currentDate = new Date();
 63 |           let finalAccessKeyUrl;
 64 |           let s3Urls = [];
 65 |           
 66 |           // Handle WebSocket keys with S3 upload
 67 |           if (accessKeyData.websocket && accessKeyData.websocket.enabled && S3_PROVIDERS_ENABLED) {
 68 |             try {
 69 |               logInfo(`Processing WebSocket key: ${accessKeyData.id}`);
 70 |               logInfo(`WebSocket configuration:`, JSON.stringify(accessKeyData.websocket));
 71 |               logInfo(`WebSocket domain: ${websocketDomain}`);
 72 |               
 73 |               // Construct the correct URL using our apiUrl from KV
 74 |               const correctDynamicUrl = `${apiEndpointUrl}/access-keys/${accessKeyData.id}`;
 75 |               logInfo(`Corrected dynamic URL: ${correctDynamicUrl}`);
 76 |               
 77 |               // Fetch the YAML content from the corrected dynamic access key URL
 78 |               logInfo('Fetching YAML content from corrected URL...');
 79 |               const yamlResponse = await fetch(correctDynamicUrl);
 80 |               if (!yamlResponse.ok) {
 81 |                 const errorText = await yamlResponse.text();
 82 |                 logError(`Failed to fetch dynamic key content. Status: ${yamlResponse.status}, Body: ${errorText}`);
 83 |                 throw new Error(`Failed to fetch dynamic key content: ${yamlResponse.status} - ${errorText}`);
 84 |               }
 85 |               const yamlContent = await yamlResponse.text();
 86 |               logInfo(`YAML content fetched, length: ${yamlContent.length} bytes`);
 87 |               
 88 |               // Extract server name from WebSocket domain
 89 |               const serverName = extractServerName(websocketDomain);
 90 |               logInfo(`Extracted server name: ${serverName}`);
 91 |               
 92 |               // Parse S3 providers and upload
 93 |               const s3Providers = parseS3Providers(env);
 94 |               logInfo(`Found ${s3Providers.length} S3 providers`);
 95 |               
 96 |               if (s3Providers.length > 0) {
 97 |                 logInfo('Starting S3 uploads...');
 98 |                 s3Urls = await uploadToMultipleS3(s3Providers, serverName, accessKeyData.id, yamlContent);
 99 |                 logInfo(`S3 upload successful. URLs: ${JSON.stringify(s3Urls)}`);
100 |                 
101 |                 // Test latency and select optimal S3 URL
102 |                 const optimalUrl = await getOptimalS3Url(s3Urls);
103 |                 finalAccessKeyUrl = `ssconf://${optimalUrl.replace('https://', '')}`;
104 |                 logInfo(`Final access key URL: ${finalAccessKeyUrl}`);
105 |               } else {
106 |                 logError('No S3 providers configured');
107 |                 throw new Error('No S3 providers configured');
108 |               }
109 |             } catch (error) {
110 |               // If S3 upload fails, delete the created key and fail
111 |               logError('S3 upload failed, cleaning up access key:', error);
112 |               logError('Error stack:', error.stack);
113 |               logError('Error details:', JSON.stringify({
114 |                 message: error.message,
115 |                 name: error.name,
116 |                 websocketDomain: websocketDomain,
117 |                 keyId: accessKeyData.id,
118 |                 websocketConfig: accessKeyData.websocket,
119 |                 correctedUrl: `${apiEndpointUrl}/access-keys/${accessKeyData.id}`,
120 |                 apiEndpointUrl: apiEndpointUrl
121 |               }));
122 |               
123 |               try {
124 |                 await deleteAccessKey(apiEndpointUrl, accessKeyData.id);
125 |                 logInfo('Successfully deleted orphaned access key');
126 |               } catch (deleteError) {
127 |                 logError('Failed to delete access key after S3 upload failure:', deleteError);
128 |               }
129 |               return new Response(`Failed to process WebSocket access key: ${error.message}`, { status: 500 });
130 |             }
131 |           } else {
132 |             // Use regular access URL for non-WebSocket keys
133 |             finalAccessKeyUrl = `${accessKeyData.accessUrl}${PREFIX_DISGUISE}`;
134 |           }
135 |           
136 |           const keyData = {
137 |             creationTime: currentDate.toISOString(),
138 |             deletionTime: null,
139 |             lastSeen: null,
140 |             currentlyConnected: null,
141 |             isWebSocket: WEBSOCKET_ENABLED && websocketDomain ? true : false,
142 |             s3Paths: s3Urls,
143 |             serverName: extractServerName(websocketDomain),
144 |             apiEndpoint: apiEndpointUrl
145 |           };
146 |           await ACCESS_KEYS_NAMESPACE.put(keyId, JSON.stringify(keyData));
147 |   
148 |           const output = generateHtmlOutput(currentDate, finalAccessKeyUrl, accessKeyData.websocket && accessKeyData.websocket.enabled ? true : false);
149 |           return new Response(output, { headers: { 'content-type': 'text/html' } });
150 |         } else {
151 |           return new Response('Failed to create access key', { status: 500 });
152 |         }
153 |       } catch (error) {
154 |         logError('Error in creating access key:', error);
155 |         if (error.message === 'No available API endpoints.') {
156 |           return new Response('Service temporarily unavailable. Please try again later.', { status: 503 });
157 |         } else {
158 |           return new Response('Error processing your request', { status: 500 });
159 |         }
160 |       }
161 |     } else {
162 |       return serveHtmlForm();
163 |     }
164 |   }
165 |   
166 |   // Function to modify the API endpoint URL based on the request hostname
167 |   function modifyApiEndpointUrl(originalApiEndpointUrl, requestHostname) {
168 |     const originalUrl = new URL(originalApiEndpointUrl);
169 |     const originalHostnameParts = originalUrl.hostname.split('.');
170 |     const requestHostnameParts = requestHostname.split('.');
171 |     if (originalHostnameParts.length > 1 && requestHostnameParts.length > 1) {
172 |       originalHostnameParts[originalHostnameParts.length - 2] = requestHostnameParts[requestHostnameParts.length - 2];
173 |       originalHostnameParts[originalHostnameParts.length - 1] = requestHostnameParts[requestHostnameParts.length - 1];
174 |       originalUrl.hostname = originalHostnameParts.join('.');
175 |     }
176 |     return originalUrl.toString();
177 |   }
178 |   
179 |   // Function to validate the form and Cloudflare Turnstile token
180 |   async function validateFormAndTurnstile(request, secret) {
181 |     const formData = await request.formData();
182 |     const token = formData.get('cf-turnstile-response');
183 |     return await verifyTurnstile(token, secret);
184 |   }
185 |   
186 |   // Function to get the optimal API endpoint based on latency and access key count
187 |   async function getOptimalApiEndpoint(namespace) {
188 |     const endpoints = await namespace.list();
189 |     const endpointScores = [];
190 |   
191 |     const fetchPromises = endpoints.keys.map(async endpoint => {
192 |       const endpointDataStr = await namespace.get(endpoint.name);
193 |       if (!endpointDataStr) return;
194 |       
195 |       let apiEndpointUrl;
196 |       try {
197 |         const endpointData = JSON.parse(endpointDataStr);
198 |         apiEndpointUrl = endpointData.apiUrl;
199 |       } catch (e) {
200 |         // Backward compatibility
201 |         apiEndpointUrl = endpointDataStr;
202 |       }
203 |       
204 |       const accessKeysUrl = `${apiEndpointUrl}/access-keys`;
205 |   
206 |       try {
207 |         const controller = new AbortController();
208 |         const timeoutId = setTimeout(() => controller.abort(), API_ENDPOINT_TIMEOUT);
209 |   
210 |         const startTime = performance.now();
211 |         const response = await fetch(accessKeysUrl, { signal: controller.signal });
212 |         const endTime = performance.now();
213 |         const latency = endTime - startTime;
214 |   
215 |         clearTimeout(timeoutId);
216 |   
217 |         if (response.ok) {
218 |           const accessKeys = await response.json();
219 |           const accessKeyCount = accessKeys.accessKeys.length;
220 |           
221 |           const score = WEIGHT_LATENCY * latency + WEIGHT_ACCESS_KEY_COUNT * accessKeyCount;
222 |           
223 |           endpointScores.push({ endpoint: endpoint.name, score });
224 |         } else {
225 |           logError(`Failed to fetch access keys from ${accessKeysUrl}. Status: ${response.status}`);
226 |         }
227 |       } catch (error) {
228 |         if (error.name === 'AbortError') {
229 |           logError(`Request to ${accessKeysUrl} timed out.`);
230 |         } else {
231 |           logError(`Error fetching access keys from ${accessKeysUrl}:`, error);
232 |         }
233 |       }
234 |     });
235 |   
236 |     try {
237 |       await Promise.all(fetchPromises);
238 |     } catch (error) {
239 |       logError('Error fetching access keys:', error);
240 |     }
241 |   
242 |     if (endpointScores.length === 0) {
243 |       throw new Error('No available API endpoints.');
244 |     }
245 |   
246 |     endpointScores.sort((a, b) => a.score - b.score);
247 |   
248 |     return endpointScores[0].endpoint;
249 |   }
250 |   
251 |   // Function to create a new access key
252 |   async function createNewAccessKey(apiEndpointUrl, websocketDomain) {
253 |     let requestBody = {};
254 |     
255 |     // If WebSocket is enabled, include WebSocket configuration
256 |     if (WEBSOCKET_ENABLED && websocketDomain) {
257 |       requestBody = {
258 |         websocket: {
259 |           enabled: true,
260 |           tcpPath: WEBSOCKET_TCP_PATH,
261 |           udpPath: WEBSOCKET_UDP_PATH,
262 |           domain: websocketDomain,
263 |           tls: WEBSOCKET_TLS
264 |         }
265 |       };
266 |     }
267 |     
268 |     const response = await fetch(apiEndpointUrl + '/access-keys', { 
269 |       method: 'POST',
270 |       headers: {
271 |         'Content-Type': 'application/json'
272 |       },
273 |       body: Object.keys(requestBody).length > 0 ? JSON.stringify(requestBody) : undefined
274 |     });
275 |     
276 |     if (response.ok) {
277 |       return await response.json();
278 |     } else {
279 |       logError('Failed to create new access key:', response.statusText);
280 |       return null;
281 |     }
282 |   }
283 |   
284 |   // Function to serve the HTML form
285 |   function serveHtmlForm() {
286 |     const htmlForm = `
287 |       <!DOCTYPE html>
288 |       <html>
289 |         <head>
290 |           <title>Get an access key</title>
291 |           <script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
292 |           <style>
293 |             body {
294 |               background-color: #1a1a1a;
295 |               color: #ffffff;
296 |               font-family: Arial, sans-serif;
297 |             }
298 |             form {
299 |               max-width: 400px;
300 |               margin: 0 auto;
301 |               padding: 20px;
302 |             }
303 |             input[type="submit"] {
304 |               background-color: #333333;
305 |               color: #ffffff;
306 |               padding: 10px 20px;
307 |               border: none;
308 |               cursor: pointer;
309 |             }
310 |           </style>
311 |         </head>
312 |         <body>
313 |           <noscript>
314 |             <p>Please enable JavaScript to access this page.</p>
315 |           </noscript>
316 |           <form action="/get" method="post">
317 |             <p>If you are human, click the check box when it shows up.</p>
318 |             <div id="turnstile-container">
319 |               <div id="turnstile-loading-text">Loading Cloudflare Turnstile widget. Please wait...</div>
320 |               <div class="cf-turnstile" data-sitekey="${turnstileSiteKey}"></div>
321 |             </div>
322 |             <p>Then click submit to get an access key.</p>
323 |             <input type="submit" value="Submit">
324 |           </form>
325 |           <script>
326 |             function checkTurnstileLoaded() {
327 |               var turnstileWidget = document.querySelector('.cf-turnstile iframe');
328 |               if (turnstileWidget) {
329 |                 var loadingText = document.getElementById('turnstile-loading-text');
330 |                 if (loadingText) {
331 |                   loadingText.parentNode.removeChild(loadingText);
332 |                 }
333 |               } else {
334 |                 setTimeout(checkTurnstileLoaded, 100);
335 |               }
336 |             }
337 |             checkTurnstileLoaded();
338 |           </script>
339 |         </body>
340 |       </html>
341 |     `;
342 |   
343 |     return new Response(htmlForm, { headers: { 'Content-Type': 'text/html' } });
344 |   }
345 |   
346 |   /**
347 |    * Internal function to delete an access key - ONLY used for cleanup on S3 upload failure
348 |    * This is NOT exposed as a public endpoint and requires the API endpoint URL
349 |    * which is only available internally after key creation
350 |    * 
351 |    * Security: This function is only called when:
352 |    * 1. A key was successfully created on the Outline server
353 |    * 2. S3 upload failed and we need to prevent orphaned keys
354 |    * 3. The API endpoint URL is already known from the creation process
355 |    * 
356 |    * @param {string} apiEndpointUrl - The Outline API endpoint (with auth path)
357 |    * @param {string} keyId - The ID of the key to delete
358 |    * @returns {Promise<boolean>} - True if deletion succeeded
359 |    */
360 |   async function deleteAccessKey(apiEndpointUrl, keyId) {
361 |     const response = await fetch(`${apiEndpointUrl}/access-keys/${keyId}`, { 
362 |       method: 'DELETE' 
363 |     });
364 |     
365 |     if (!response.ok) {
366 |       throw new Error(`Failed to delete access key: ${response.status}`);
367 |     }
368 |     
369 |     return true;
370 |   }
371 |   
372 |   // Function to generate the HTML output for the access key
373 |   function generateHtmlOutput(currentDate, accessKeyOutput, isWebSocketKey = false) {
374 |     const keyTypeMessage = isWebSocketKey 
375 |       ? '<p style="color: #4ade80;"><strong>WebSocket-enabled key generated!</strong> This key uses advanced censorship-resistant technology.</p>' 
376 |       : '';
377 |     
378 |     return `
379 |       <!DOCTYPE html>
380 |       <html>
381 |         <head>
382 |           <title>Access key generated</title>
383 |           <style>
384 |             body {
385 |               background-color: #1a1a1a;
386 |               color: #ffffff;
387 |               font-family: Arial, sans-serif;
388 |             }
389 |             .container {
390 |               max-width: 600px;
391 |               margin: 0 auto;
392 |               padding: 20px;
393 |             }
394 |             .access-key-box {
395 |               background-color: #282828;
396 |               border: 1px solid #444444;
397 |               padding: 10px;
398 |               margin-bottom: 10px;
399 |               cursor: pointer;
400 |               word-wrap: break-word;
401 |             }
402 |             .copy-button {
403 |               background-color: #333333;
404 |               color: #ffffff;
405 |               padding: 5px 10px;
406 |               border: none;
407 |               cursor: pointer;
408 |             }
409 |           </style>
410 |         </head>
411 |         <body>
412 |           <div class="container">
413 |             <h2>Access key generated</h2>
414 |             ${keyTypeMessage}
415 |             <p>Creation date: ${currentDate.toISOString()}</p>
416 |             <p>Expiration date: This key will intelligently expire after ${EXPIRATION_DAYS} days if you don't use it.</p>
417 |             <p>Access key:</p>
418 |             <div class="access-key-box" onclick="copyToClipboard('${accessKeyOutput}')">
419 |               <p>${accessKeyOutput}</p>
420 |             </div>
421 |             <button class="copy-button" onclick="copyToClipboard('${accessKeyOutput}')">Copy Access Key</button>
422 |             <script>
423 |               function copyToClipboard(text) {
424 |                 navigator.clipboard.writeText(text).then(function() {
425 |                   alert('Access key copied to clipboard');
426 |                 }, function() {
427 |                   alert('Failed to copy access key');
428 |                 });
429 |               }
430 |             </script>
431 |           </div>
432 |         </body>
433 |       </html>
434 |     `;
435 |   }


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
  1 |                     GNU GENERAL PUBLIC LICENSE
  2 |                        Version 3, 29 June 2007
  3 | 
  4 |  Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
  5 |  Everyone is permitted to copy and distribute verbatim copies
  6 |  of this license document, but changing it is not allowed.
  7 | 
  8 |                             Preamble
  9 | 
 10 |   The GNU General Public License is a free, copyleft license for
 11 | software and other kinds of works.
 12 | 
 13 |   The licenses for most software and other practical works are designed
 14 | to take away your freedom to share and change the works.  By contrast,
 15 | the GNU General Public License is intended to guarantee your freedom to
 16 | share and change all versions of a program--to make sure it remains free
 17 | software for all its users.  We, the Free Software Foundation, use the
 18 | GNU General Public License for most of our software; it applies also to
 19 | any other work released this way by its authors.  You can apply it to
 20 | your programs, too.
 21 | 
 22 |   When we speak of free software, we are referring to freedom, not
 23 | price.  Our General Public Licenses are designed to make sure that you
 24 | have the freedom to distribute copies of free software (and charge for
 25 | them if you wish), that you receive source code or can get it if you
 26 | want it, that you can change the software or use pieces of it in new
 27 | free programs, and that you know you can do these things.
 28 | 
 29 |   To protect your rights, we need to prevent others from denying you
 30 | these rights or asking you to surrender the rights.  Therefore, you have
 31 | certain responsibilities if you distribute copies of the software, or if
 32 | you modify it: responsibilities to respect the freedom of others.
 33 | 
 34 |   For example, if you distribute copies of such a program, whether
 35 | gratis or for a fee, you must pass on to the recipients the same
 36 | freedoms that you received.  You must make sure that they, too, receive
 37 | or can get the source code.  And you must show them these terms so they
 38 | know their rights.
 39 | 
 40 |   Developers that use the GNU GPL protect your rights with two steps:
 41 | (1) assert copyright on the software, and (2) offer you this License
 42 | giving you legal permission to copy, distribute and/or modify it.
 43 | 
 44 |   For the developers' and authors' protection, the GPL clearly explains
 45 | that there is no warranty for this free software.  For both users' and
 46 | authors' sake, the GPL requires that modified versions be marked as
 47 | changed, so that their problems will not be attributed erroneously to
 48 | authors of previous versions.
 49 | 
 50 |   Some devices are designed to deny users access to install or run
 51 | modified versions of the software inside them, although the manufacturer
 52 | can do so.  This is fundamentally incompatible with the aim of
 53 | protecting users' freedom to change the software.  The systematic
 54 | pattern of such abuse occurs in the area of products for individuals to
 55 | use, which is precisely where it is most unacceptable.  Therefore, we
 56 | have designed this version of the GPL to prohibit the practice for those
 57 | products.  If such problems arise substantially in other domains, we
 58 | stand ready to extend this provision to those domains in future versions
 59 | of the GPL, as needed to protect the freedom of users.
 60 | 
 61 |   Finally, every program is threatened constantly by software patents.
 62 | States should not allow patents to restrict development and use of
 63 | software on general-purpose computers, but in those that do, we wish to
 64 | avoid the special danger that patents applied to a free program could
 65 | make it effectively proprietary.  To prevent this, the GPL assures that
 66 | patents cannot be used to render the program non-free.
 67 | 
 68 |   The precise terms and conditions for copying, distribution and
 69 | modification follow.
 70 | 
 71 |                        TERMS AND CONDITIONS
 72 | 
 73 |   0. Definitions.
 74 | 
 75 |   "This License" refers to version 3 of the GNU General Public License.
 76 | 
 77 |   "Copyright" also means copyright-like laws that apply to other kinds of
 78 | works, such as semiconductor masks.
 79 | 
 80 |   "The Program" refers to any copyrightable work licensed under this
 81 | License.  Each licensee is addressed as "you".  "Licensees" and
 82 | "recipients" may be individuals or organizations.
 83 | 
 84 |   To "modify" a work means to copy from or adapt all or part of the work
 85 | in a fashion requiring copyright permission, other than the making of an
 86 | exact copy.  The resulting work is called a "modified version" of the
 87 | earlier work or a work "based on" the earlier work.
 88 | 
 89 |   A "covered work" means either the unmodified Program or a work based
 90 | on the Program.
 91 | 
 92 |   To "propagate" a work means to do anything with it that, without
 93 | permission, would make you directly or secondarily liable for
 94 | infringement under applicable copyright law, except executing it on a
 95 | computer or modifying a private copy.  Propagation includes copying,
 96 | distribution (with or without modification), making available to the
 97 | public, and in some countries other activities as well.
 98 | 
 99 |   To "convey" a work means any kind of propagation that enables other
100 | parties to make or receive copies.  Mere interaction with a user through
101 | a computer network, with no transfer of a copy, is not conveying.
102 | 
103 |   An interactive user interface displays "Appropriate Legal Notices"
104 | to the extent that it includes a convenient and prominently visible
105 | feature that (1) displays an appropriate copyright notice, and (2)
106 | tells the user that there is no warranty for the work (except to the
107 | extent that warranties are provided), that licensees may convey the
108 | work under this License, and how to view a copy of this License.  If
109 | the interface presents a list of user commands or options, such as a
110 | menu, a prominent item in the list meets this criterion.
111 | 
112 |   1. Source Code.
113 | 
114 |   The "source code" for a work means the preferred form of the work
115 | for making modifications to it.  "Object code" means any non-source
116 | form of a work.
117 | 
118 |   A "Standard Interface" means an interface that either is an official
119 | standard defined by a recognized standards body, or, in the case of
120 | interfaces specified for a particular programming language, one that
121 | is widely used among developers working in that language.
122 | 
123 |   The "System Libraries" of an executable work include anything, other
124 | than the work as a whole, that (a) is included in the normal form of
125 | packaging a Major Component, but which is not part of that Major
126 | Component, and (b) serves only to enable use of the work with that
127 | Major Component, or to implement a Standard Interface for which an
128 | implementation is available to the public in source code form.  A
129 | "Major Component", in this context, means a major essential component
130 | (kernel, window system, and so on) of the specific operating system
131 | (if any) on which the executable work runs, or a compiler used to
132 | produce the work, or an object code interpreter used to run it.
133 | 
134 |   The "Corresponding Source" for a work in object code form means all
135 | the source code needed to generate, install, and (for an executable
136 | work) run the object code and to modify the work, including scripts to
137 | control those activities.  However, it does not include the work's
138 | System Libraries, or general-purpose tools or generally available free
139 | programs which are used unmodified in performing those activities but
140 | which are not part of the work.  For example, Corresponding Source
141 | includes interface definition files associated with source files for
142 | the work, and the source code for shared libraries and dynamically
143 | linked subprograms that the work is specifically designed to require,
144 | such as by intimate data communication or control flow between those
145 | subprograms and other parts of the work.
146 | 
147 |   The Corresponding Source need not include anything that users
148 | can regenerate automatically from other parts of the Corresponding
149 | Source.
150 | 
151 |   The Corresponding Source for a work in source code form is that
152 | same work.
153 | 
154 |   2. Basic Permissions.
155 | 
156 |   All rights granted under this License are granted for the term of
157 | copyright on the Program, and are irrevocable provided the stated
158 | conditions are met.  This License explicitly affirms your unlimited
159 | permission to run the unmodified Program.  The output from running a
160 | covered work is covered by this License only if the output, given its
161 | content, constitutes a covered work.  This License acknowledges your
162 | rights of fair use or other equivalent, as provided by copyright law.
163 | 
164 |   You may make, run and propagate covered works that you do not
165 | convey, without conditions so long as your license otherwise remains
166 | in force.  You may convey covered works to others for the sole purpose
167 | of having them make modifications exclusively for you, or provide you
168 | with facilities for running those works, provided that you comply with
169 | the terms of this License in conveying all material for which you do
170 | not control copyright.  Those thus making or running the covered works
171 | for you must do so exclusively on your behalf, under your direction
172 | and control, on terms that prohibit them from making any copies of
173 | your copyrighted material outside their relationship with you.
174 | 
175 |   Conveying under any other circumstances is permitted solely under
176 | the conditions stated below.  Sublicensing is not allowed; section 10
177 | makes it unnecessary.
178 | 
179 |   3. Protecting Users' Legal Rights From Anti-Circumvention Law.
180 | 
181 |   No covered work shall be deemed part of an effective technological
182 | measure under any applicable law fulfilling obligations under article
183 | 11 of the WIPO copyright treaty adopted on 20 December 1996, or
184 | similar laws prohibiting or restricting circumvention of such
185 | measures.
186 | 
187 |   When you convey a covered work, you waive any legal power to forbid
188 | circumvention of technological measures to the extent such circumvention
189 | is effected by exercising rights under this License with respect to
190 | the covered work, and you disclaim any intention to limit operation or
191 | modification of the work as a means of enforcing, against the work's
192 | users, your or third parties' legal rights to forbid circumvention of
193 | technological measures.
194 | 
195 |   4. Conveying Verbatim Copies.
196 | 
197 |   You may convey verbatim copies of the Program's source code as you
198 | receive it, in any medium, provided that you conspicuously and
199 | appropriately publish on each copy an appropriate copyright notice;
200 | keep intact all notices stating that this License and any
201 | non-permissive terms added in accord with section 7 apply to the code;
202 | keep intact all notices of the absence of any warranty; and give all
203 | recipients a copy of this License along with the Program.
204 | 
205 |   You may charge any price or no price for each copy that you convey,
206 | and you may offer support or warranty protection for a fee.
207 | 
208 |   5. Conveying Modified Source Versions.
209 | 
210 |   You may convey a work based on the Program, or the modifications to
211 | produce it from the Program, in the form of source code under the
212 | terms of section 4, provided that you also meet all of these conditions:
213 | 
214 |     a) The work must carry prominent notices stating that you modified
215 |     it, and giving a relevant date.
216 | 
217 |     b) The work must carry prominent notices stating that it is
218 |     released under this License and any conditions added under section
219 |     7.  This requirement modifies the requirement in section 4 to
220 |     "keep intact all notices".
221 | 
222 |     c) You must license the entire work, as a whole, under this
223 |     License to anyone who comes into possession of a copy.  This
224 |     License will therefore apply, along with any applicable section 7
225 |     additional terms, to the whole of the work, and all its parts,
226 |     regardless of how they are packaged.  This License gives no
227 |     permission to license the work in any other way, but it does not
228 |     invalidate such permission if you have separately received it.
229 | 
230 |     d) If the work has interactive user interfaces, each must display
231 |     Appropriate Legal Notices; however, if the Program has interactive
232 |     interfaces that do not display Appropriate Legal Notices, your
233 |     work need not make them do so.
234 | 
235 |   A compilation of a covered work with other separate and independent
236 | works, which are not by their nature extensions of the covered work,
237 | and which are not combined with it such as to form a larger program,
238 | in or on a volume of a storage or distribution medium, is called an
239 | "aggregate" if the compilation and its resulting copyright are not
240 | used to limit the access or legal rights of the compilation's users
241 | beyond what the individual works permit.  Inclusion of a covered work
242 | in an aggregate does not cause this License to apply to the other
243 | parts of the aggregate.
244 | 
245 |   6. Conveying Non-Source Forms.
246 | 
247 |   You may convey a covered work in object code form under the terms
248 | of sections 4 and 5, provided that you also convey the
249 | machine-readable Corresponding Source under the terms of this License,
250 | in one of these ways:
251 | 
252 |     a) Convey the object code in, or embodied in, a physical product
253 |     (including a physical distribution medium), accompanied by the
254 |     Corresponding Source fixed on a durable physical medium
255 |     customarily used for software interchange.
256 | 
257 |     b) Convey the object code in, or embodied in, a physical product
258 |     (including a physical distribution medium), accompanied by a
259 |     written offer, valid for at least three years and valid for as
260 |     long as you offer spare parts or customer support for that product
261 |     model, to give anyone who possesses the object code either (1) a
262 |     copy of the Corresponding Source for all the software in the
263 |     product that is covered by this License, on a durable physical
264 |     medium customarily used for software interchange, for a price no
265 |     more than your reasonable cost of physically performing this
266 |     conveying of source, or (2) access to copy the
267 |     Corresponding Source from a network server at no charge.
268 | 
269 |     c) Convey individual copies of the object code with a copy of the
270 |     written offer to provide the Corresponding Source.  This
271 |     alternative is allowed only occasionally and noncommercially, and
272 |     only if you received the object code with such an offer, in accord
273 |     with subsection 6b.
274 | 
275 |     d) Convey the object code by offering access from a designated
276 |     place (gratis or for a charge), and offer equivalent access to the
277 |     Corresponding Source in the same way through the same place at no
278 |     further charge.  You need not require recipients to copy the
279 |     Corresponding Source along with the object code.  If the place to
280 |     copy the object code is a network server, the Corresponding Source
281 |     may be on a different server (operated by you or a third party)
282 |     that supports equivalent copying facilities, provided you maintain
283 |     clear directions next to the object code saying where to find the
284 |     Corresponding Source.  Regardless of what server hosts the
285 |     Corresponding Source, you remain obligated to ensure that it is
286 |     available for as long as needed to satisfy these requirements.
287 | 
288 |     e) Convey the object code using peer-to-peer transmission, provided
289 |     you inform other peers where the object code and Corresponding
290 |     Source of the work are being offered to the general public at no
291 |     charge under subsection 6d.
292 | 
293 |   A separable portion of the object code, whose source code is excluded
294 | from the Corresponding Source as a System Library, need not be
295 | included in conveying the object code work.
296 | 
297 |   A "User Product" is either (1) a "consumer product", which means any
298 | tangible personal property which is normally used for personal, family,
299 | or household purposes, or (2) anything designed or sold for incorporation
300 | into a dwelling.  In determining whether a product is a consumer product,
301 | doubtful cases shall be resolved in favor of coverage.  For a particular
302 | product received by a particular user, "normally used" refers to a
303 | typical or common use of that class of product, regardless of the status
304 | of the particular user or of the way in which the particular user
305 | actually uses, or expects or is expected to use, the product.  A product
306 | is a consumer product regardless of whether the product has substantial
307 | commercial, industrial or non-consumer uses, unless such uses represent
308 | the only significant mode of use of the product.
309 | 
310 |   "Installation Information" for a User Product means any methods,
311 | procedures, authorization keys, or other information required to install
312 | and execute modified versions of a covered work in that User Product from
313 | a modified version of its Corresponding Source.  The information must
314 | suffice to ensure that the continued functioning of the modified object
315 | code is in no case prevented or interfered with solely because
316 | modification has been made.
317 | 
318 |   If you convey an object code work under this section in, or with, or
319 | specifically for use in, a User Product, and the conveying occurs as
320 | part of a transaction in which the right of possession and use of the
321 | User Product is transferred to the recipient in perpetuity or for a
322 | fixed term (regardless of how the transaction is characterized), the
323 | Corresponding Source conveyed under this section must be accompanied
324 | by the Installation Information.  But this requirement does not apply
325 | if neither you nor any third party retains the ability to install
326 | modified object code on the User Product (for example, the work has
327 | been installed in ROM).
328 | 
329 |   The requirement to provide Installation Information does not include a
330 | requirement to continue to provide support service, warranty, or updates
331 | for a work that has been modified or installed by the recipient, or for
332 | the User Product in which it has been modified or installed.  Access to a
333 | network may be denied when the modification itself materially and
334 | adversely affects the operation of the network or violates the rules and
335 | protocols for communication across the network.
336 | 
337 |   Corresponding Source conveyed, and Installation Information provided,
338 | in accord with this section must be in a format that is publicly
339 | documented (and with an implementation available to the public in
340 | source code form), and must require no special password or key for
341 | unpacking, reading or copying.
342 | 
343 |   7. Additional Terms.
344 | 
345 |   "Additional permissions" are terms that supplement the terms of this
346 | License by making exceptions from one or more of its conditions.
347 | Additional permissions that are applicable to the entire Program shall
348 | be treated as though they were included in this License, to the extent
349 | that they are valid under applicable law.  If additional permissions
350 | apply only to part of the Program, that part may be used separately
351 | under those permissions, but the entire Program remains governed by
352 | this License without regard to the additional permissions.
353 | 
354 |   When you convey a copy of a covered work, you may at your option
355 | remove any additional permissions from that copy, or from any part of
356 | it.  (Additional permissions may be written to require their own
357 | removal in certain cases when you modify the work.)  You may place
358 | additional permissions on material, added by you to a covered work,
359 | for which you have or can give appropriate copyright permission.
360 | 
361 |   Notwithstanding any other provision of this License, for material you
362 | add to a covered work, you may (if authorized by the copyright holders of
363 | that material) supplement the terms of this License with terms:
364 | 
365 |     a) Disclaiming warranty or limiting liability differently from the
366 |     terms of sections 15 and 16 of this License; or
367 | 
368 |     b) Requiring preservation of specified reasonable legal notices or
369 |     author attributions in that material or in the Appropriate Legal
370 |     Notices displayed by works containing it; or
371 | 
372 |     c) Prohibiting misrepresentation of the origin of that material, or
373 |     requiring that modified versions of such material be marked in
374 |     reasonable ways as different from the original version; or
375 | 
376 |     d) Limiting the use for publicity purposes of names of licensors or
377 |     authors of the material; or
378 | 
379 |     e) Declining to grant rights under trademark law for use of some
380 |     trade names, trademarks, or service marks; or
381 | 
382 |     f) Requiring indemnification of licensors and authors of that
383 |     material by anyone who conveys the material (or modified versions of
384 |     it) with contractual assumptions of liability to the recipient, for
385 |     any liability that these contractual assumptions directly impose on
386 |     those licensors and authors.
387 | 
388 |   All other non-permissive additional terms are considered "further
389 | restrictions" within the meaning of section 10.  If the Program as you
390 | received it, or any part of it, contains a notice stating that it is
391 | governed by this License along with a term that is a further
392 | restriction, you may remove that term.  If a license document contains
393 | a further restriction but permits relicensing or conveying under this
394 | License, you may add to a covered work material governed by the terms
395 | of that license document, provided that the further restriction does
396 | not survive such relicensing or conveying.
397 | 
398 |   If you add terms to a covered work in accord with this section, you
399 | must place, in the relevant source files, a statement of the
400 | additional terms that apply to those files, or a notice indicating
401 | where to find the applicable terms.
402 | 
403 |   Additional terms, permissive or non-permissive, may be stated in the
404 | form of a separately written license, or stated as exceptions;
405 | the above requirements apply either way.
406 | 
407 |   8. Termination.
408 | 
409 |   You may not propagate or modify a covered work except as expressly
410 | provided under this License.  Any attempt otherwise to propagate or
411 | modify it is void, and will automatically terminate your rights under
412 | this License (including any patent licenses granted under the third
413 | paragraph of section 11).
414 | 
415 |   However, if you cease all violation of this License, then your
416 | license from a particular copyright holder is reinstated (a)
417 | provisionally, unless and until the copyright holder explicitly and
418 | finally terminates your license, and (b) permanently, if the copyright
419 | holder fails to notify you of the violation by some reasonable means
420 | prior to 60 days after the cessation.
421 | 
422 |   Moreover, your license from a particular copyright holder is
423 | reinstated permanently if the copyright holder notifies you of the
424 | violation by some reasonable means, this is the first time you have
425 | received notice of violation of this License (for any work) from that
426 | copyright holder, and you cure the violation prior to 30 days after
427 | your receipt of the notice.
428 | 
429 |   Termination of your rights under this section does not terminate the
430 | licenses of parties who have received copies or rights from you under
431 | this License.  If your rights have been terminated and not permanently
432 | reinstated, you do not qualify to receive new licenses for the same
433 | material under section 10.
434 | 
435 |   9. Acceptance Not Required for Having Copies.
436 | 
437 |   You are not required to accept this License in order to receive or
438 | run a copy of the Program.  Ancillary propagation of a covered work
439 | occurring solely as a consequence of using peer-to-peer transmission
440 | to receive a copy likewise does not require acceptance.  However,
441 | nothing other than this License grants you permission to propagate or
442 | modify any covered work.  These actions infringe copyright if you do
443 | not accept this License.  Therefore, by modifying or propagating a
444 | covered work, you indicate your acceptance of this License to do so.
445 | 
446 |   10. Automatic Licensing of Downstream Recipients.
447 | 
448 |   Each time you convey a covered work, the recipient automatically
449 | receives a license from the original licensors, to run, modify and
450 | propagate that work, subject to this License.  You are not responsible
451 | for enforcing compliance by third parties with this License.
452 | 
453 |   An "entity transaction" is a transaction transferring control of an
454 | organization, or substantially all assets of one, or subdividing an
455 | organization, or merging organizations.  If propagation of a covered
456 | work results from an entity transaction, each party to that
457 | transaction who receives a copy of the work also receives whatever
458 | licenses to the work the party's predecessor in interest had or could
459 | give under the previous paragraph, plus a right to possession of the
460 | Corresponding Source of the work from the predecessor in interest, if
461 | the predecessor has it or can get it with reasonable efforts.
462 | 
463 |   You may not impose any further restrictions on the exercise of the
464 | rights granted or affirmed under this License.  For example, you may
465 | not impose a license fee, royalty, or other charge for exercise of
466 | rights granted under this License, and you may not initiate litigation
467 | (including a cross-claim or counterclaim in a lawsuit) alleging that
468 | any patent claim is infringed by making, using, selling, offering for
469 | sale, or importing the Program or any portion of it.
470 | 
471 |   11. Patents.
472 | 
473 |   A "contributor" is a copyright holder who authorizes use under this
474 | License of the Program or a work on which the Program is based.  The
475 | work thus licensed is called the contributor's "contributor version".
476 | 
477 |   A contributor's "essential patent claims" are all patent claims
478 | owned or controlled by the contributor, whether already acquired or
479 | hereafter acquired, that would be infringed by some manner, permitted
480 | by this License, of making, using, or selling its contributor version,
481 | but do not include claims that would be infringed only as a
482 | consequence of further modification of the contributor version.  For
483 | purposes of this definition, "control" includes the right to grant
484 | patent sublicenses in a manner consistent with the requirements of
485 | this License.
486 | 
487 |   Each contributor grants you a non-exclusive, worldwide, royalty-free
488 | patent license under the contributor's essential patent claims, to
489 | make, use, sell, offer for sale, import and otherwise run, modify and
490 | propagate the contents of its contributor version.
491 | 
492 |   In the following three paragraphs, a "patent license" is any express
493 | agreement or commitment, however denominated, not to enforce a patent
494 | (such as an express permission to practice a patent or covenant not to
495 | sue for patent infringement).  To "grant" such a patent license to a
496 | party means to make such an agreement or commitment not to enforce a
497 | patent against the party.
498 | 
499 |   If you convey a covered work, knowingly relying on a patent license,
500 | and the Corresponding Source of the work is not available for anyone
501 | to copy, free of charge and under the terms of this License, through a
502 | publicly available network server or other readily accessible means,
503 | then you must either (1) cause the Corresponding Source to be so
504 | available, or (2) arrange to deprive yourself of the benefit of the
505 | patent license for this particular work, or (3) arrange, in a manner
506 | consistent with the requirements of this License, to extend the patent
507 | license to downstream recipients.  "Knowingly relying" means you have
508 | actual knowledge that, but for the patent license, your conveying the
509 | covered work in a country, or your recipient's use of the covered work
510 | in a country, would infringe one or more identifiable patents in that
511 | country that you have reason to believe are valid.
512 | 
513 |   If, pursuant to or in connection with a single transaction or
514 | arrangement, you convey, or propagate by procuring conveyance of, a
515 | covered work, and grant a patent license to some of the parties
516 | receiving the covered work authorizing them to use, propagate, modify
517 | or convey a specific copy of the covered work, then the patent license
518 | you grant is automatically extended to all recipients of the covered
519 | work and works based on it.
520 | 
521 |   A patent license is "discriminatory" if it does not include within
522 | the scope of its coverage, prohibits the exercise of, or is
523 | conditioned on the non-exercise of one or more of the rights that are
524 | specifically granted under this License.  You may not convey a covered
525 | work if you are a party to an arrangement with a third party that is
526 | in the business of distributing software, under which you make payment
527 | to the third party based on the extent of your activity of conveying
528 | the work, and under which the third party grants, to any of the
529 | parties who would receive the covered work from you, a discriminatory
530 | patent license (a) in connection with copies of the covered work
531 | conveyed by you (or copies made from those copies), or (b) primarily
532 | for and in connection with specific products or compilations that
533 | contain the covered work, unless you entered into that arrangement,
534 | or that patent license was granted, prior to 28 March 2007.
535 | 
536 |   Nothing in this License shall be construed as excluding or limiting
537 | any implied license or other defenses to infringement that may
538 | otherwise be available to you under applicable patent law.
539 | 
540 |   12. No Surrender of Others' Freedom.
541 | 
542 |   If conditions are imposed on you (whether by court order, agreement or
543 | otherwise) that contradict the conditions of this License, they do not
544 | excuse you from the conditions of this License.  If you cannot convey a
545 | covered work so as to satisfy simultaneously your obligations under this
546 | License and any other pertinent obligations, then as a consequence you may
547 | not convey it at all.  For example, if you agree to terms that obligate you
548 | to collect a royalty for further conveying from those to whom you convey
549 | the Program, the only way you could satisfy both those terms and this
550 | License would be to refrain entirely from conveying the Program.
551 | 
552 |   13. Use with the GNU Affero General Public License.
553 | 
554 |   Notwithstanding any other provision of this License, you have
555 | permission to link or combine any covered work with a work licensed
556 | under version 3 of the GNU Affero General Public License into a single
557 | combined work, and to convey the resulting work.  The terms of this
558 | License will continue to apply to the part which is the covered work,
559 | but the special requirements of the GNU Affero General Public License,
560 | section 13, concerning interaction through a network will apply to the
561 | combination as such.
562 | 
563 |   14. Revised Versions of this License.
564 | 
565 |   The Free Software Foundation may publish revised and/or new versions of
566 | the GNU General Public License from time to time.  Such new versions will
567 | be similar in spirit to the present version, but may differ in detail to
568 | address new problems or concerns.
569 | 
570 |   Each version is given a distinguishing version number.  If the
571 | Program specifies that a certain numbered version of the GNU General
572 | Public License "or any later version" applies to it, you have the
573 | option of following the terms and conditions either of that numbered
574 | version or of any later version published by the Free Software
575 | Foundation.  If the Program does not specify a version number of the
576 | GNU General Public License, you may choose any version ever published
577 | by the Free Software Foundation.
578 | 
579 |   If the Program specifies that a proxy can decide which future
580 | versions of the GNU General Public License can be used, that proxy's
581 | public statement of acceptance of a version permanently authorizes you
582 | to choose that version for the Program.
583 | 
584 |   Later license versions may give you additional or different
585 | permissions.  However, no additional obligations are imposed on any
586 | author or copyright holder as a result of your choosing to follow a
587 | later version.
588 | 
589 |   15. Disclaimer of Warranty.
590 | 
591 |   THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
592 | APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
593 | HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
594 | OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
595 | THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
596 | PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
597 | IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
598 | ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
599 | 
600 |   16. Limitation of Liability.
601 | 
602 |   IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
603 | WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
604 | THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
605 | GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
606 | USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
607 | DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
608 | PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
609 | EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
610 | SUCH DAMAGES.
611 | 
612 |   17. Interpretation of Sections 15 and 16.
613 | 
614 |   If the disclaimer of warranty and limitation of liability provided
615 | above cannot be given local legal effect according to their terms,
616 | reviewing courts shall apply local law that most closely approximates
617 | an absolute waiver of all civil liability in connection with the
618 | Program, unless a warranty or assumption of liability accompanies a
619 | copy of the Program in return for a fee.
620 | 
621 |                      END OF TERMS AND CONDITIONS
622 | 
623 |             How to Apply These Terms to Your New Programs
624 | 
625 |   If you develop a new program, and you want it to be of the greatest
626 | possible use to the public, the best way to achieve this is to make it
627 | free software which everyone can redistribute and change under these terms.
628 | 
629 |   To do so, attach the following notices to the program.  It is safest
630 | to attach them to the start of each source file to most effectively
631 | state the exclusion of warranty; and each file should have at least
632 | the "copyright" line and a pointer to where the full notice is found.
633 | 
634 |     <one line to give the program's name and a brief idea of what it does.>
635 |     Copyright (C) <year>  <name of author>
636 | 
637 |     This program is free software: you can redistribute it and/or modify
638 |     it under the terms of the GNU General Public License as published by
639 |     the Free Software Foundation, either version 3 of the License, or
640 |     (at your option) any later version.
641 | 
642 |     This program is distributed in the hope that it will be useful,
643 |     but WITHOUT ANY WARRANTY; without even the implied warranty of
644 |     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
645 |     GNU General Public License for more details.
646 | 
647 |     You should have received a copy of the GNU General Public License
648 |     along with this program.  If not, see <https://www.gnu.org/licenses/>.
649 | 
650 | Also add information on how to contact you by electronic and paper mail.
651 | 
652 |   If the program does terminal interaction, make it output a short
653 | notice like this when it starts in an interactive mode:
654 | 
655 |     <program>  Copyright (C) <year>  <name of author>
656 |     This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
657 |     This is free software, and you are welcome to redistribute it
658 |     under certain conditions; type `show c' for details.
659 | 
660 | The hypothetical commands `show w' and `show c' should show the appropriate
661 | parts of the General Public License.  Of course, your program's commands
662 | might be different; for a GUI interface, you would use an "about box".
663 | 
664 |   You should also get your employer (if you work as a programmer) or school,
665 | if any, to sign a "copyright disclaimer" for the program, if necessary.
666 | For more information on this, and how to apply and follow the GNU GPL, see
667 | <https://www.gnu.org/licenses/>.
668 | 
669 |   The GNU General Public License does not permit incorporating your program
670 | into proprietary programs.  If your program is a subroutine library, you
671 | may consider it more useful to permit linking proprietary applications with
672 | the library.  If this is what you want to do, use the GNU Lesser General
673 | Public License instead of this License.  But first, please read
674 | <https://www.gnu.org/licenses/why-not-lgpl.html>.
675 | 


--------------------------------------------------------------------------------