BIJAY'S Toolkit

1. Overview & architecture

BIJAY'S Toolkit is a static site + serverless functions on Vercel in front of a private GitHub repository. The repo holds all content (scripts, app catalogs, config, docs). Small Node functions in api/ talk to GitHub using a token that lives only on the server, so client PCs never see the token or the private repo — they just receive text over HTTPS.

Two independent front doors:

• The launcher — a self-contained WPF GUI in public/launcher.ps1 that renders the repo's folders as a UI and calls /api/list and /api/get to read content.
• The admin panel — a single-file web app in public/admin/index.html that reads via /api/tree//api/get and writes via /api/write//api/delete.

2. The GitHub repository

How the repo side was set up (and how to recreate it):

1. Create a private repository on GitHub (e.g. waytobijay/Msp-Toolkit). Private is important — push access equals code-execution on every client PC.
2. Push the project (api/, public/, data/, vercel.json, package.json). No build step and no runtime dependencies — package.json just pins the Node engine.
3. Create a fine-grained Personal Access Token scoped to this repository only, with Contents: Read and write (write is needed for the admin panel). Give it an expiry and rotate it periodically.
4. The token is never committed. It's stored as a Vercel environment variable (see §9). Locally, secrets go in a git-ignored .env; example.env is a template only.

3. GitHub as the data store

There is no database. GitHub is the store, accessed through two REST APIs:

• Contents API — GET /repos/{repo}/contents/{path} lists a folder or returns a file; PUT creates/updates a file (base64 body + the current sha for updates); DELETE removes one. Used by list/get/write/delete.
• Git Trees API — GET /repos/{repo}/git/trees/{ref}?recursive=1 returns the entire file tree in one call. Used by the admin panel to build its sidebar.

Every write is an ordinary commit, so the full history and audit trail live in git. Admin commits are messaged admin: <create|update|delete> <path>.

4. The Vercel API proxy

Each file in api/ is one serverless function. They share a pattern: read env config, check the caller's key, call GitHub with the server-side token, return text/JSON. Reads for client content send Cache-Control: no-store.

The launcher sends its access password as the x-launcher-key header on every call; the admin panel sends x-admin-key. When a launcher key is configured, list/get accept either key so the admin UI keeps reading files. api/write.js rejects paths containing .., leading slashes, or segments with trailing spaces/dots (which can't be checked out on Windows).

5. Serving the launcher

api/root.js sniffs the User-Agent:

• If it looks like a shell (powershell/curl/wget), it fetches public/launcher.ps1 from GitHub (Accept: application/vnd.github.raw) and returns it as text/plain with no-store — so irm | iex always runs the latest version, no cache-busting.
• Otherwise it 302-redirects to /admin so humans who open the domain land on the console.

The launcher itself is UI-only: it pulls listings and file text through the API and never contains a token. Its version is shown in the window header ($script:Version).

6. Routing (vercel.json)

{
  "rewrites": [
    { "source": "/",         "destination": "/api/root" },
    { "source": "/launcher", "destination": "/api/root" },
    { "source": "/linux",    "destination": "/api/linux-root" },
    { "source": "/console",  "destination": "/api/console" },
    { "source": "/admin",    "destination": "/admin/index.html" }
  ],
  "functions": { "api/*.js": { "maxDuration": 10 } }
}

Static assets under public/ are served directly, so the docs live at /documentation/…. Rewrites map the friendly paths to functions/pages.

7. Data model

Naming & conventions

• Script set = a folder under data/scripts/. Section = a subfolder. Script = NN-name.ps1 (NN orders; display name derived from the filename).
• Linux mirrors this under data/linux/ with .sh scripts. The Linux launcher (public/linux.sh, served at /linux) reads them via /api/tree + /api/get with the same x-launcher-key, and runs / schedules them in a terminal menu. .sh files are pinned to LF via .gitattributes so curl | bash never gets CRLF.
• config.json at a set root is data (never a section); it's hidden in the admin tree and edited via the gear.
• A data/software folder that contains apps.json is an App Catalog; folders without it are custom-script folders.
• Header comments # Title:, # Description:, # Icon: drive the launcher cards.

8. App Catalog & winget

A catalog is a JSON file — an array of categories, each with an array of apps:

{
  "categories": [
    { "name": "Browsers", "apps": [
      { "name": "Google Chrome", "winget": "Google.Chrome", "icon": "chrome",
        "desc": "Fast web browser from Google." }
    ] }
  ]
}

The launcher renders it as a categorised checkbox grid (with a per-category Select all). Install Selected opens one elevated window that installs each ticked app:

winget install --id <Id> --exact --source winget --silent \
  --accept-package-agreements --accept-source-agreements

• --source winget pins the community repo so the interactive msstore region/agreement prompt can't block the silent batch.
• The runner normalises the Id — a bare Publisher.App or a pasted full winget install … command both resolve to the Id.
• If winget is missing, it attempts to install "App Installer" first.

Multiple catalogs are supported: the root apps.json plus any data/software/<name>/apps.json. The launcher caches each by path and clears the selection when you switch catalogs. In the admin panel these are managed by the form editor (openCatalogEditor(path)), and + → New app catalog seeds a new folder catalog with one sample category and app.

9. Environment variables

Set in Vercel → Settings → Environment Variables (Production). Changes apply on the next deploy.

10. Security model

• Token isolation — the GitHub token exists only in Vercel env vars. Client PCs and browsers reach only /api/*; they never see the token or the private repo.
• No edge caching of gated reads — /api/list and /api/get send Cache-Control: no-store, so an authenticated response can't be cached and later served to an unauthenticated request. /api/get is restricted to data/.
• Two independent gates — LAUNCHER_KEY protects the launcher; ADMIN_PASSWORD protects /admin and every write/delete. Destructive admin actions re-prompt for the password client-side before committing.
• Trust boundary — irm | iex executes remote code as the launching user. Keep the repo private and push access tight; anyone who can push can run code on every client PC.

11. Deploy & how updates go live

1. Push the repo to private GitHub.
2. Import it into Vercel (vercel.com/new) — no build settings; functions in api/, static public/.
3. Add the environment variables (§9) and deploy.
4. (Optional) Point a custom domain at the project, then set $script:BaseUrl at the top of public/launcher.ps1 to that domain and push once.

12. Maintaining & extending

• Add scripts/apps/config — via the admin panel or git. Never hand-edit launcher.ps1 for content.
• Change the launcher UI — edit public/launcher.ps1 (embedded XAML + PowerShell) and bump $script:Version. It's live on push.
• Add an API endpoint — drop a api/<name>.js function following the existing pattern (env config → key check → GitHub call). Add a rewrite in vercel.json if you want a friendly path.
• Icons — the launcher maps keywords to Segoe MDL2 glyphs (extend the icon map in launcher.ps1); a script/app can force one with # Icon: / the catalog icon field.
• Rotate the token before it expires; update GITHUB_TOKEN in Vercel and redeploy.

13. Version history (highlights)