@enderrealmmc/cf-static-guard 0.1.0

package/README.md

@@ -0,0 +1,125 @@
+# @enderrealmmc/cf-static-guard
+
+Deploy any static site behind GitHub OAuth on Cloudflare Workers — without cloning the monorepo.
+
+- **Worker is bundled in this package** — install the CLI and deploy
+- **No files written into your site repo** — profiles live in `~/.config/csg` (or `%APPDATA%/csg`)
+- **Rules & branding on Cloudflare** — edit via `/admin` or `csg config`
+- Login + admin UIs included (Vue 3, prebuilt)
+
+## Install
+
+```bash
+npm i -g @enderrealmmc/cf-static-guard
+# requires Node.js >= 20
+```
+
+You also need a Cloudflare account. The CLI depends on [wrangler](https://developers.cloudflare.com/workers/wrangler/).
+
+## Quick start
+
+```bash
+csg auth                          # wrangler login (browser)
+csg init                          # interactive: worker name, GitHub OAuth, secrets, KV
+csg deploy --site ./dist          # your static build output
+```
+
+Open the custom domain or workers.dev URL, sign in with GitHub, then manage rules at `/admin`.
+
+### Non-interactive / CI
+
+```bash
+export CSG_GITHUB_CLIENT_ID=...
+export CSG_GITHUB_CLIENT_SECRET=...
+export CSG_SESSION_SECRET=...      # optional; auto-generated if unset
+export CSG_ADMIN_PASSWORD=...      # optional; auto-generated if unset
+
+csg init \
+  --name my-docs \
+  --mode strict \
+  --non-interactive \
+  --create-kv \
+  --custom-domain docs.example.com \
+  --redirect-base https://docs.example.com
+
+csg deploy --site ./docs/.vitepress/dist
+```
+
+## Everyday commands
+
+| Command | What it does |
+|---------|----------------|
+| `csg deploy --site <dir>` | Deploy/refresh Worker + static assets (temp dir only) |
+| `csg config get` | Show local profile + try pull KV |
+| `csg config set-mode strict\|normal` | Change mode and push KV |
+| `csg config allow-add <login>` | Allowlist a GitHub login |
+| `csg config org-add <org>` | Require org membership (strict) |
+| `csg config ui set icp "京ICP备..."` | Branding / ICP text |
+| `csg secrets set` | Set Worker secrets |
+| `csg kv create` | Create `RULES` KV namespace |
+| `csg profile list\|use` | Multiple workers |
+| `csg open admin --base https://...` | Open admin panel |
+| `csg doctor` | Check login, bundle, config |
+
+## Where things live
+
+| Data | Location |
+|------|----------|
+| Worker name, KV id, local rule draft | Global config (`~/.config/csg` or `%APPDATA%/csg`) |
+| OAuth secrets, session, admin password | Cloudflare Worker Secrets |
+| Strict rules, UI texts, ICP | Cloudflare KV (`auth:config`, `ui:config`) |
+| Your website files | Your machine; only used as `--site` input |
+
+**This CLI does not create `csg.config.json` in your project.**
+
+## Strict mode rules
+
+Per GitHub provider (fields you leave empty are skipped; filled fields that fail deny access):
+
+- `allowlist` / `blocklist`
+- `minAccountAgeDays`
+- `requiredOrgs`
+- `requiredTeams` (`org/team`)
+- `emailDomainAllowlist`
+
+`blocklist` applies in both normal and strict mode.
+
+## GitHub OAuth App
+
+Create one under your user or org:
+
+| Field | Value |
+|-------|--------|
+| Homepage URL | `https://<your-domain>` |
+| Callback URL | `https://<your-domain>/auth/callback/github` |
+
+Then pass Client ID/Secret to `csg init` or `csg secrets set`.
+
+## Custom domain
+
+```bash
+csg init --custom-domain docs.example.com --redirect-base https://docs.example.com ...
+```
+
+Zone must already be on the same Cloudflare account. First attach may take a minute for DNS/TLS.
+
+## Admin panel
+
+After deploy: `https://<your-domain>/admin`
+
+Password is `ADMIN_PASSWORD` (set during `init`). Use it to edit rules and login-page text without redeploying static assets.
+
+Update site content anytime:
+
+```bash
+csg deploy --site ./path/to/dist
+```
+
+## Monorepo development
+
+This package is built from [EnderRealmMC/cf-static-guard](https://github.com/EnderRealmMC/cf-static-guard).  
+`prepack` compiles the CLI and copies the prebuilt Worker into `dist-worker/`.
+
+## License
+
+MIT

package/bin/csg.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { run } from '../dist/index.js';
+
+run(process.argv).catch((err) => {
+  console.error(err instanceof Error ? err.message : err);
+  process.exit(1);
+});

package/dist/commands/auth.js

@@ -0,0 +1,16 @@
+import { runWranglerInherit } from '../lib/wrangler.js';
+import { success, info } from '../lib/log.js';
+export function registerAuth(program) {
+    program
+        .command('auth')
+        .description('Log in to Cloudflare via wrangler (opens browser)')
+        .action(async () => {
+        info('Running wrangler login…');
+        const code = await runWranglerInherit(['login']);
+        if (code !== 0) {
+            process.exitCode = code;
+            return;
+        }
+        success('Cloudflare login OK');
+    });
+}

package/dist/commands/config.js

@@ -0,0 +1,253 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { getProfile, loadStore, upsertProfile, } from '../lib/store.js';
+import { error, success, warn, info } from '../lib/log.js';
+import { applyAuthToProfile, applyUiToProfile, profileToAuthConfig, profileToUiConfig, pullAuthConfig, pullUiConfig, pushAuthConfig, pushUiConfig, } from '../lib/kv.js';
+function requireProfile(name) {
+    const p = getProfile(name);
+    if (!p) {
+        throw new Error('No profile. Run `csg init` first.');
+    }
+    return p;
+}
+function save(p) {
+    const store = loadStore();
+    upsertProfile(p, store.defaultProfile === p.name || !store.profiles[p.name]);
+}
+function rulesOf(p) {
+    if (!p.providers.github) {
+        p.providers.github = { enabled: true, rules: {} };
+    }
+    if (!p.providers.github.rules)
+        p.providers.github.rules = {};
+    return p.providers.github.rules;
+}
+export function registerConfig(program) {
+    const config = program
+        .command('config')
+        .description('Read/write live KV config (same JSON as /admin). Does not write into your site repo.');
+    config
+        .command('get')
+        .description('Print local profile + try pull online auth/ui')
+        .option('-p, --profile <name>', 'profile name')
+        .action(async (opts) => {
+        const p = requireProfile(opts.profile);
+        console.log(JSON.stringify({ local: p }, null, 2));
+        if (!p.kvNamespaceId) {
+            warn('No KV id — skip online pull');
+            return;
+        }
+        try {
+            const auth = await pullAuthConfig(p);
+            const ui = await pullUiConfig(p);
+            console.log(JSON.stringify({ online: { auth, ui } }, null, 2));
+        }
+        catch (e) {
+            warn(e instanceof Error ? e.message : String(e));
+        }
+    });
+    config
+        .command('set-mode <mode>')
+        .description('Set normal|strict on profile and push to KV')
+        .option('-p, --profile <name>', 'profile name')
+        .option('--no-push', 'Only update local profile')
+        .action(async (mode, opts) => {
+        if (mode !== 'normal' && mode !== 'strict') {
+            error('mode must be normal or strict');
+            process.exitCode = 1;
+            return;
+        }
+        const p = requireProfile(opts.profile);
+        p.mode = mode;
+        p.updatedAt = new Date().toISOString();
+        save(p);
+        success(`Local mode → ${mode}`);
+        if (opts.push !== false && p.kvNamespaceId) {
+            await pushAuthConfig(p);
+            success('Pushed auth:config to KV');
+        }
+    });
+    config
+        .command('allow-add <login>')
+        .description('Add login to GitHub allowlist and push')
+        .option('-p, --profile <name>')
+        .option('--no-push')
+        .action(async (login, opts) => {
+        const p = requireProfile(opts.profile);
+        const rules = rulesOf(p);
+        rules.allowlist = rules.allowlist || [];
+        if (!rules.allowlist.includes(login))
+            rules.allowlist.push(login);
+        p.updatedAt = new Date().toISOString();
+        save(p);
+        success(`allowlist += ${login}`);
+        if (opts.push !== false && p.kvNamespaceId) {
+            await pushAuthConfig(p);
+            success('Pushed auth:config');
+        }
+    });
+    config
+        .command('allow-remove <login>')
+        .description('Remove login from allowlist and push')
+        .option('-p, --profile <name>')
+        .option('--no-push')
+        .action(async (login, opts) => {
+        const p = requireProfile(opts.profile);
+        const rules = rulesOf(p);
+        rules.allowlist = (rules.allowlist || []).filter((x) => x !== login);
+        p.updatedAt = new Date().toISOString();
+        save(p);
+        success(`allowlist -= ${login}`);
+        if (opts.push !== false && p.kvNamespaceId) {
+            await pushAuthConfig(p);
+            success('Pushed auth:config');
+        }
+    });
+    config
+        .command('org-add <org>')
+        .description('Add required GitHub org and push')
+        .option('-p, --profile <name>')
+        .option('--no-push')
+        .action(async (org, opts) => {
+        const p = requireProfile(opts.profile);
+        const rules = rulesOf(p);
+        rules.requiredOrgs = rules.requiredOrgs || [];
+        if (!rules.requiredOrgs.includes(org))
+            rules.requiredOrgs.push(org);
+        p.mode = p.mode === 'normal' ? 'strict' : p.mode;
+        p.updatedAt = new Date().toISOString();
+        save(p);
+        success(`requiredOrgs += ${org}`);
+        if (opts.push !== false && p.kvNamespaceId) {
+            await pushAuthConfig(p);
+            success('Pushed auth:config');
+        }
+    });
+    config
+        .command('ui')
+        .description('UI text helpers')
+        .argument('<key>', 'e.g. loginHeading, copyright, icp, footerBrand, siteTitle')
+        .argument('[value]', 'new value; omit to print current')
+        .option('-p, --profile <name>')
+        .option('--no-push')
+        .action(async (key, value, opts) => {
+        const p = requireProfile(opts.profile);
+        p.ui = p.ui || {};
+        const allowed = new Set([
+            'siteTitle',
+            'siteSubtitle',
+            'loginHeading',
+            'loginSubtitle',
+            'providerButtonPrefix',
+            'footerBrand',
+            'copyright',
+            'icp',
+            'icpLink',
+        ]);
+        const boolKeys = new Set([
+            'showModeBadge',
+            'showFooterBrand',
+            'showGithubIcon',
+        ]);
+        if (!allowed.has(key) && !boolKeys.has(key)) {
+            error(`Unknown ui key: ${key}`);
+            process.exitCode = 1;
+            return;
+        }
+        if (value === undefined) {
+            console.log(p.ui[key]);
+            return;
+        }
+        if (boolKeys.has(key)) {
+            p.ui[key] =
+                value === 'true' || value === '1' || value === 'yes';
+        }
+        else {
+            p.ui[key] = value;
+        }
+        p.updatedAt = new Date().toISOString();
+        save(p);
+        success(`ui.${key} = ${value}`);
+        if (opts.push !== false && p.kvNamespaceId) {
+            await pushUiConfig(p);
+            success('Pushed ui:config');
+        }
+    });
+    config
+        .command('pull')
+        .description('Pull online auth/ui into local profile (still not in your site repo)')
+        .option('-p, --profile <name>')
+        .option('--apply', 'Merge into local profile and save', true)
+        .action(async (opts) => {
+        const p = requireProfile(opts.profile);
+        if (!p.kvNamespaceId) {
+            error('No KV id on profile');
+            process.exitCode = 1;
+            return;
+        }
+        const auth = await pullAuthConfig(p);
+        const ui = await pullUiConfig(p);
+        let next = p;
+        if (auth)
+            next = applyAuthToProfile(next, auth);
+        if (ui)
+            next = applyUiToProfile(next, ui);
+        if (opts.apply !== false) {
+            save(next);
+            success('Local profile updated from KV');
+        }
+        console.log(JSON.stringify({ auth, ui }, null, 2));
+    });
+    config
+        .command('push')
+        .description('Push local profile auth+ui to KV')
+        .option('-p, --profile <name>')
+        .option('--json <file>', 'Optional: read auth config JSON from file instead of profile')
+        .action(async (opts) => {
+        const p = requireProfile(opts.profile);
+        if (!p.kvNamespaceId) {
+            error('No KV id on profile');
+            process.exitCode = 1;
+            return;
+        }
+        if (opts.json) {
+            const raw = readFileSync(resolve(process.cwd(), opts.json), 'utf8');
+            const parsed = JSON.parse(raw);
+            await pushAuthConfig({
+                ...p,
+                mode: parsed.mode || p.mode,
+                providers: {
+                    github: {
+                        enabled: parsed.providers?.github?.enabled !== false,
+                        mode: parsed.providers?.github?.mode,
+                        rules: parsed.providers?.github?.rules || {},
+                    },
+                },
+            });
+            await pushUiConfig(p);
+            success(`Pushed auth from ${opts.json} + ui from profile`);
+            return;
+        }
+        await pushAuthConfig(p);
+        await pushUiConfig(p);
+        success('Pushed auth:config + ui:config');
+        info(`Local snapshot: ${JSON.stringify(profileToAuthConfig(p))}`);
+        info(`UI snapshot: ${JSON.stringify(profileToUiConfig(p))}`);
+    });
+    config
+        .command('export')
+        .description('Print a backup JSON of local profile to stdout')
+        .option('-p, --profile <name>')
+        .option('-o, --output <file>', 'Write to file instead of stdout')
+        .action((opts) => {
+        const p = requireProfile(opts.profile);
+        const json = JSON.stringify(p, null, 2) + '\n';
+        if (opts.output) {
+            writeFileSync(resolve(process.cwd(), opts.output), json, 'utf8');
+            success(`Wrote ${opts.output}`);
+        }
+        else {
+            process.stdout.write(json);
+        }
+    });
+}

package/dist/commands/deploy.js

@@ -0,0 +1,65 @@
+import { resolve } from 'node:path';
+import { getProfile, loadStore } from '../lib/store.js';
+import { error, info, step, success, warn } from '../lib/log.js';
+import { prepareDeployDir } from '../lib/deploy.js';
+import { runWranglerInherit } from '../lib/wrangler.js';
+import { pushAuthConfig, pushUiConfig } from '../lib/kv.js';
+export function registerDeploy(program) {
+    program
+        .command('deploy')
+        .description('Deploy/refresh worker + static assets (temp dir only; does not write into your project)')
+        .requiredOption('-s, --site <dir>', 'Path to static build output (dist)')
+        .option('-p, --profile <name>', 'Profile name (default: global default)')
+        .option('-m, --mode <mode>', 'Override mode for this deploy: normal|strict')
+        .option('--spa', 'Force SPA fallback on for this deploy')
+        .option('--push-config', 'Also push auth/ui config from profile to KV')
+        .option('--dry-run', 'Prepare temp dir and run wrangler deploy --dry-run')
+        .action(async (opts) => {
+        const store = loadStore();
+        const profile = getProfile(opts.profile);
+        if (!profile) {
+            error(opts.profile
+                ? `Profile not found: ${opts.profile}`
+                : 'No profile. Run `csg init` first.');
+            process.exitCode = 1;
+            return;
+        }
+        const site = resolve(process.cwd(), opts.site);
+        const effective = {
+            ...profile,
+            mode: opts.mode === 'strict' ? 'strict' : opts.mode === 'normal' ? 'normal' : profile.mode,
+            spaFallback: opts.spa ? true : profile.spaFallback,
+        };
+        info(`Profile: ${effective.name} (default=${store.defaultProfile})`);
+        info(`Site:    ${site}`);
+        info(`Mode:    ${effective.mode}`);
+        if (!effective.kvNamespaceId) {
+            warn('KV not configured — admin/config online edits will not persist.');
+        }
+        step('Preparing temp deploy directory…');
+        const dirs = prepareDeployDir(effective, site);
+        try {
+            info(`Temp: ${dirs.root}`);
+            step('Running wrangler deploy…');
+            const code = await runWranglerInherit(opts.dryRun
+                ? ['deploy', '-c', 'wrangler.toml', '--dry-run']
+                : ['deploy', '-c', 'wrangler.toml'], { cwd: dirs.root });
+            if (code !== 0) {
+                error('wrangler deploy failed');
+                process.exitCode = code;
+                return;
+            }
+            success('Deploy finished');
+            if (opts.pushConfig && effective.kvNamespaceId) {
+                step('Pushing profile config to KV…');
+                await pushAuthConfig(effective);
+                await pushUiConfig(effective);
+                success('KV config updated');
+            }
+            success(`https://${effective.name}.\${your-subdomain}.workers.dev  (or your custom domain)`);
+        }
+        finally {
+            dirs.cleanup();
+        }
+    });
+}

package/dist/commands/doctor.js

@@ -0,0 +1,41 @@
+import { error, info, success, warn } from '../lib/log.js';
+import { cliVersion, hasWorkerBundle } from '../lib/paths.js';
+import { configPath, listProfileNames, loadStore } from '../lib/store.js';
+import { whoami } from '../lib/cf.js';
+import { wranglerBin } from '../lib/wrangler.js';
+export function registerDoctor(program) {
+    program
+        .command('doctor')
+        .description('Check Node, wrangler login, worker bundle, and global config')
+        .action(async () => {
+        info(`csg ${cliVersion()}`);
+        info(`node ${process.version}`);
+        info(`wrangler bin: ${wranglerBin()}`);
+        if (hasWorkerBundle()) {
+            success('worker bundle present (dist-worker/worker.js)');
+        }
+        else {
+            warn('worker bundle missing — reinstall package or run monorepo build');
+        }
+        const store = loadStore();
+        info(`config: ${configPath()}`);
+        const names = listProfileNames();
+        if (names.length === 0) {
+            warn('no profiles yet — run `csg init`');
+        }
+        else {
+            success(`profiles: ${names.join(', ')} (default: ${store.defaultProfile})`);
+        }
+        const auth = await whoami();
+        if (auth.ok) {
+            success('wrangler authenticated');
+            console.log(auth.text);
+        }
+        else {
+            error('wrangler not logged in — run `csg auth`');
+            if (auth.text)
+                console.log(auth.text);
+            process.exitCode = 1;
+        }
+    });
+}