BIJAY'S Toolkit

1. I am locked out — fix it now ADMIN

After 8 wrong passwords the API blocks that network. The block also rejects the correct password — deliberately, otherwise it would not slow an attacker down. Pick the first option that suits you.

npx vercel --prod
# or simply push any commit
git commit --allow-empty -m "clear lockout" && git push

curl -H "x-recovery-key: <your-recovery-key>" https://toolkit.bistab.com.np/api/tree

Invoke-RestMethod -Uri "https://toolkit.bistab.com.np/api/tree" `
  -Headers @{ "x-recovery-key" = "<your-recovery-key>" }

2. I forgot the admin password ADMIN

There is no password reset email — the password is an environment variable. Change it:

1. Vercel dashboard → your project → Settings → Environment Variables.
2. Find ADMIN_PASSWORD → Edit.
3. Paste a new strong value (generate one below) → Save.
4. Go to Deployments → ⋯ → Redeploy. Env changes only take effect on a new deployment.
5. Sign in with the new password. The redeploy also cleared any lockout.

Generate a strong password:

node -e "console.log(require('crypto').randomBytes(24).toString('base64url'))"

3. Break-glass recovery key ADMIN

Optional but recommended — it turns a lockout from "wait or redeploy" into a one-line fix.

1. Generate a key (must be 32+ characters or it is ignored):

   node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

2. Vercel → Settings → Environment Variables → Add New.
3. Name ADMIN_RECOVERY_KEY, paste the value, select all environments, Save.
4. Redeploy so it takes effect.
5. Store it somewhere you can reach when locked out — a password manager, not this repo.

Why this is not just a second, weaker password

• Only someone who can already read Vercel env vars can use it — and they could change ADMIN_PASSWORD anyway, so it grants nothing new.
• Keys under 32 characters are rejected outright, so it cannot be guessed within the request ceiling that still applies to it.
• It is compared in constant time, like every other secret.
• Leave the variable unset and no bypass exists at all.

4. How the lockout works

Credential scopes are isolated

Lockouts are keyed by IP plus which credential was attempted. In practice:

• A PC with a stale MSP_KEY retrying the launcher cannot lock you out of /admin.
• Someone brute-forcing the admin password cannot lock out managed launcher clients.

5. Security model & credentials

Nothing sensitive ever reaches a client. The browser and the launcher talk only to the Vercel API, which holds the GitHub token server-side and proxies the repo.

Launcher / Admin browser
        │   x-launcher-key  or  x-admin-key
        ▼
   Vercel API  (api/_guard.js gates every route)
        │   Authorization: Bearer GITHUB_TOKEN   ← never leaves the server
        ▼
   Private GitHub repo (data/ subtree only)

6. What is protected

7. Audit findings & fixes

From the security review of the whole codebase. Kept here so the reasoning is not lost.

CRITICAL Admin writes were not confined to data/

write.js and delete.js only checked for path traversal, never for the data/ prefix that every read route enforced. A leaked or guessed admin password could therefore overwrite public/launcher.ps1 — the script every managed endpoint executes via irm | iex — turning admin access into remote code execution across the fleet.

FIXED Both routes now use the shared validator and are confined to data/.

HIGH No rate limiting anywhere

/api/tree doubles as the login oracle (the admin UI validates the password against it), so the single shared password could be guessed at full speed, unthrottled and unlogged.

FIXED Per-IP limiting plus escalating lockout on every route.

MEDIUM The rest

• Timing-unsafe comparison — !== on secrets short-circuits. Now constant-time.
• No security headers — CSP, nosniff, DENY, HSTS and Referrer-Policy added to both API and static responses.
• Unencoded paths — filenames containing spaces, brackets or an en-dash built malformed GitHub URLs, causing 404/502. Every segment is now percent-encoded.
• Non-ASCII downloads — Content-Disposition threw on names like “02) Printer Setup – HP DesignJet T870.docx”. Now RFC 5987 encoded.
• Stored XSS via uploaded markup — HTML/XML now download instead of rendering.
• Unpinned CDN scripts ran with full admin privileges — now SRI-pinned.
• Error detail leakage — upstream errors logged server-side, generic response returned.

8. Launcher-side security

The same protections cover the PowerShell launcher, because it authenticates server-side — not with a local password check that could be edited out.

• console.ps1 retries /api/list and re-prompts while it gets 401.
• launcher.ps1 shows its login overlay on 401 from /api/tree.
• Both now report a 429 plainly — "too many attempts from this network" with the wait time — instead of a misleading "cannot reach API".

No footprint on client machines

• The launcher runs from memory (irm | iex); nothing is installed.
• Theme choice is kept in memory only — no file is written.
• Temporary runner scripts self-delete, and Clear-Footprint sweeps stale ones.
• The API key is read from the client's own MSP_KEY environment variable; it is never embedded in the served script.

9. Setting up secrets

1. Vercel → project → Settings → Environment Variables.
2. Add each variable from section 5, ticking every environment you use.
3. Redeploy — env changes only apply to new deployments.
4. Never commit secrets. .env and .env.* are gitignored; keep it that way.

Set MSP_KEY on a client PC so the launcher signs in without prompting:

[Environment]::SetEnvironmentVariable('MSP_KEY','<launcher key>','User')

10. Verifying it still works

The protections have an automated suite. Run it after touching anything under api/:

node test/security.test.js    # 30 checks — auth, escalation, traversal, headers
node test/lockout.test.js     # 15 checks — backoff, recovery key, both login surfaces
node test/startup.test.js     #  7 checks — admin loads its landing page
node test/relocate.test.js    # 13 checks — rename/move/copy never hangs

All four should end with ALL n CHECKS PASSED. They use a mocked GitHub API, so they are safe to run offline and touch nothing real.

11. Hardening backlog

Not code-fixable here — operational choices worth making:

1. Rotate ADMIN_PASSWORD to a long random string. It is the only credential and is held in the browser's sessionStorage.
2. Scope GITHUB_TOKEN to a fine-grained PAT with Contents read/write on this repo only, then rotate it.
3. Move rate-limit counters to Vercel KV / Upstash for hard cross-instance limits. Unlocking would then mean deleting the KV key rather than redeploying.
4. Enable Deployment Protection on preview deployments, so branch URLs do not expose the same API with the same env vars.
5. Set LAUNCHER_KEY if the scripts in data/ are sensitive.