|
1 | 1 | # Strategy Switch Admin Backend |
2 | 2 |
|
3 | | -Goal: keep the personal strategy switch console simple while avoiding code changes for every login or account dropdown update. |
| 3 | +Goal: keep the open-source switch page public and read-only by default, while allowing an authenticated admin to manage who can switch strategies and which account routes appear in the dropdown. |
4 | 4 |
|
5 | | -## Current Mode |
| 5 | +## Current Implementation |
6 | 6 |
|
7 | | -- GitHub OAuth signs users in. |
8 | | -- `ALLOWED_GITHUB_LOGINS` controls who can dispatch a switch. |
9 | | -- `STRATEGY_SWITCH_ACCOUNT_OPTIONS_JSON` controls signed-in account dropdowns. |
10 | | -- The GitHub dispatch token stays in Worker secrets and is never sent to the browser. |
| 7 | +- Login method: GitHub OAuth 2.0. |
| 8 | +- Public access: unsigned visitors can view the page, but cannot dispatch the workflow. |
| 9 | +- Allowed switch users: `ALLOWED_GITHUB_LOGINS`, KV `auth_config.allowed_logins`, and all admins. |
| 10 | +- Admin users: `STRATEGY_SWITCH_ADMIN_LOGINS` plus KV `auth_config.admin_logins`. |
| 11 | +- Account dropdowns: KV `account_options` first, falling back to `STRATEGY_SWITCH_ACCOUNT_OPTIONS_JSON`. |
| 12 | +- Audit log: each admin save appends to KV `audit_log`, capped at 50 entries. |
11 | 13 |
|
12 | | -This is enough for the first deployment. Its main limitation is that user and account changes require updating Worker secrets. |
| 14 | +## Cloudflare KV |
13 | 15 |
|
14 | | -## Recommended Admin Mode |
| 16 | +Bind the namespace: |
15 | 17 |
|
16 | | -Keep GitHub OAuth and use an admin-only `/admin` page: |
| 18 | +```toml |
| 19 | +[[kv_namespaces]] |
| 20 | +binding = "STRATEGY_SWITCH_CONFIG" |
| 21 | +id = "..." |
| 22 | +``` |
17 | 23 |
|
18 | | -- Bootstrap admins come from `STRATEGY_SWITCH_ADMIN_LOGINS`; keep your own GitHub login there. |
19 | | -- Admin actions: |
20 | | - - The current version verifies admin identity and shows configured account counts for the four platforms. |
21 | | - - After KV is connected, add or remove allowed GitHub logins. |
22 | | - - After KV is connected, edit account dropdowns for the four platforms. |
23 | | - - After KV is connected, review recent permission and account-config changes. |
24 | | -- Storage: |
25 | | - - Cloudflare KV namespace: `STRATEGY_SWITCH_CONFIG`. |
26 | | - - key `auth_config`: `allowed_logins` and `admin_logins`. |
27 | | - - key `account_options`: platform account dropdowns. |
28 | | - - key `audit_log`: recent admin changes. |
| 24 | +KV keys: |
| 25 | + |
| 26 | +```text |
| 27 | +auth_config |
| 28 | +account_options |
| 29 | +audit_log |
| 30 | +``` |
| 31 | + |
| 32 | +Without the KV binding, `/admin` is read-only and the Worker falls back to secrets. |
29 | 33 |
|
30 | 34 | ## Permission Rules |
31 | 35 |
|
32 | 36 | - Not signed in: public read-only page. |
33 | | -- Signed in but not allowlisted: no switch, no admin page. |
| 37 | +- Signed in but not allowlisted: no switch and no admin page. |
34 | 38 | - Allowlisted: can dispatch switches. |
35 | | -- Admin-listed: can manage login permissions and account dropdowns. |
36 | | -- `STRATEGY_SWITCH_ADMIN_LOGINS` remains the break-glass admin source so you cannot remove yourself through the UI. |
| 39 | +- Admin-listed: can open `/admin` and manage allowed logins, admin logins, and account dropdown JSON. |
| 40 | +- `STRATEGY_SWITCH_ADMIN_LOGINS` remains the break-glass admin source and is preserved on save. |
37 | 41 |
|
38 | 42 | ## Security Boundary |
39 | 43 |
|
40 | 44 | - The admin backend stores GitHub logins and account routing metadata only. |
41 | 45 | - Broker passwords, tokens, API keys, and cloud credentials stay out of this config. |
42 | | -- Admin writes use POST and the existing Worker same-origin checks. |
43 | | -- Sessions keep HttpOnly, Secure, SameSite=Lax, and HMAC-signed cookies. |
44 | | -- Dispatch tokens remain separate from admin config and are never readable from frontend code. |
45 | | -- Audit logs record time, admin login, and action type, but never secrets. |
46 | | - |
47 | | -## Rollout |
48 | | - |
49 | | -1. Ship the current secret-backed console. |
50 | | -2. The read-only `/admin` verification page is already available for `STRATEGY_SWITCH_ADMIN_LOGINS`. |
51 | | -3. Add Worker KV reads with secret fallback. |
52 | | -4. Add `/api/admin/config` write operations for admins. |
53 | | -5. Add audit logs and last-version rollback. |
| 46 | +- Admin writes use POST and same-origin checks. |
| 47 | +- Sessions use HttpOnly, Secure, SameSite=Lax, and HMAC-signed cookies. |
| 48 | +- The GitHub dispatch token stays in Worker secrets and is never returned to frontend or admin APIs. |
54 | 49 |
|
55 | | -This avoids a database, custom user system, or broad RBAC while still giving a practical backend for a personal open-source project. |
| 50 | +This keeps the personal system simple: no database, review flow, or custom RBAC, while preventing strangers from operating the public page. |
0 commit comments