chore: plugin auth (#28)

Author: lukepolo

plugins/backend.md

@@ -47,49 +47,85 @@ headers below.
 
 ## Identity in your backend
 
-Do not implement Steam OpenID, and do not try to parse the 5Stack session cookie.
-Put your service behind 5Stack's forward-auth endpoint instead: the 5Stack API
-validates the session and passes the identity to you as headers.
+Do not implement Steam OpenID, and do not try to decode the 5Stack session
+cookie — it is signed and `httpOnly`, and its contents are not a stable contract.
 
-On Kubernetes with the nginx ingress:
-
-```yaml
-nginx.ingress.kubernetes.io/auth-url: "http://api.5stack.svc.cluster.local:5585/custom-pages/authorize"
-nginx.ingress.kubernetes.io/auth-response-headers: "X-5stack-Steam-Id,X-5stack-Role,X-5stack-Name"
-```
-
-Your backend then trusts three headers:
-
-| Header              | Contents                           |
-| ------------------- | ---------------------------------- |
-| `X-5stack-Steam-Id` | The authenticated user's SteamID64 |
-| `X-5stack-Role`     | Their 5Stack role                  |
-| `X-5stack-Name`     | Their display name                 |
+Instead, hand the cookie back to us. Every request the browser makes to your
+backend already carries the 5Stack session cookie (see
+[Hosting](#hosting-is-part-of-the-security-model)). Forward it to the panel's
+authorize endpoint and you get the identity as JSON:
 
 ```ts
 // identity.ts
-export function identify(req: FastifyRequest) {
-  const steamId = req.headers["x-5stack-steam-id"] as string | undefined;
-  if (!steamId) {
-    // Local dev only. The NODE_ENV guard makes a leaked DEV_STEAM_ID harmless
-    // in production, where the ingress rejects unauthenticated requests anyway.
-    if (process.env.NODE_ENV !== "production" && process.env.DEV_STEAM_ID) {
-      return { steamId: process.env.DEV_STEAM_ID, role: "administrator" };
-    }
+const AUTH_URL =
+  process.env.FIVESTACK_AUTH_URL ??
+  "http://api.5stack.svc.cluster.local:5585/plugins/authorize";
+
+export async function identify(req: FastifyRequest) {
+  const cookie = req.headers.cookie;
+  if (!cookie) {
+    return null;
+  }
+
+  const res = await fetch(AUTH_URL, { headers: { cookie } });
+  if (!res.ok) {
     return null;
   }
-  return {
-    steamId,
-    role: req.headers["x-5stack-role"] as string,
-    name: req.headers["x-5stack-name"] as string,
+
+  return (await res.json()) as {
+    steam_id: string;
+    role: string;
+    name: string;
   };
 }
 ```
 
-::: danger These headers are only trustworthy behind the gate
-They are plain HTTP headers. If your backend is reachable without passing through
-the forward-auth ingress, anyone can set them. Never expose the service directly,
-and keep any `DEV_STEAM_ID`-style fallback strictly out of production.
+A `200` means the session is valid. `401` means there is no session. Treat
+anything non-`200` as anonymous.
+
+::: tip Cache the lookup
+This is one extra in-cluster round-trip per request. Cache the result for a few
+seconds keyed on the cookie value — long enough to collapse a page's burst of
+API calls, short enough that a logout takes effect promptly.
+:::
+
+This fails closed. If your backend is misconfigured or unexpectedly reachable,
+the worst case is that requests are rejected — never that an attacker is
+believed.
+
+### Optional: forward-auth at the ingress
+
+If you would rather spend the round-trip once at the edge than once per request
+in your process, nginx can call the same endpoint for you and inject the result
+as headers:
+
+```yaml
+nginx.ingress.kubernetes.io/auth-url: "http://api.5stack.svc.cluster.local:5585/plugins/authorize"
+nginx.ingress.kubernetes.io/auth-response-headers: "X-5stack-Steam-Id,X-5stack-Role,X-5stack-Name"
+```
+
+| Header              | Contents                                       |
+| ------------------- | ---------------------------------------------- |
+| `X-5stack-Steam-Id` | The authenticated user's SteamID64             |
+| `X-5stack-Role`     | Their 5Stack role                              |
+| `X-5stack-Name`     | Their display name, URI-encoded                |
+
+::: danger This mode fails open — know what you are signing up for
+These are plain HTTP headers. nginx overwrites them on the way through, so they
+are trustworthy *only* on traffic that actually traversed that ingress. Expose
+the Service any other way — a second ingress without the annotations, a
+NodePort, a LoadBalancer, a port-forward — and `curl -H "X-5stack-Role:
+administrator"` is an admin session. Nothing will warn you.
+
+Prefer the cookie check above unless you have measured a reason not to. If you
+do use this mode, keep the backend a `ClusterIP` Service with the annotated
+ingress as its only route in.
+:::
+
+::: warning Never ship a `DEV_STEAM_ID` escape hatch unguarded
+A local-dev fallback that returns an `administrator` when no identity is present
+is unauthenticated admin the moment that variable exists in a real environment.
+Guard it on `process.env.NODE_ENV !== "production"`, not on a comment.
 :::
 
 ## Calling your API from the plugin
@@ -105,7 +141,8 @@ const API_BASE =
 
 export async function get<T>(path: string): Promise<T> {
   const res = await fetch(`${API_BASE}/api${path}`, {
-    // Required — carries the 5Stack session cookie to the forward-auth gate.
+    // Required — carries the 5Stack session cookie, which is the only thing
+    // that lets your backend establish who is calling.
     credentials: "include",
   });
   if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
@@ -116,7 +153,7 @@ export async function get<T>(path: string): Promise<T> {
 Two details matter:
 
 - **`credentials: "include"` on every request.** Without it the session cookie
-  never reaches the gate and the ingress rejects you. This also applies to plain
+  never arrives and every request is anonymous. This also applies to plain
   `<img>` tags pointing at gated endpoints, which send cookies automatically only
   when same-site.
 - **CORS with credentials.** Your backend must reflect the requesting origin and
@@ -126,10 +163,33 @@ Two details matter:
   await app.register(cors, { origin: true, credentials: true });
   ```
 
-::: tip Hosting on a subdomain of the panel
-Serving your plugin from `myplugin.panel.example.com` keeps the 5Stack session
-cookie same-site, which sidesteps a whole category of third-party-cookie
-problems. It is the simplest arrangement that works.
+## Hosting is part of the security model
+
+**Your backend must be served from a subdomain of the panel's domain** —
+`myplugin.panel.example.com` for a panel at `panel.example.com`. This is a
+requirement, not a preference.
+
+The 5Stack session cookie is issued for `.panel.example.com` with the browser
+default `SameSite=Lax`. Lax cookies are not attached to cross-site subresource
+requests, so a backend on an unrelated domain receives no cookie at all — no
+matter what `credentials: "include"` says, and no matter how the ingress is
+annotated. Identity is simply unavailable there.
+
+Two useful consequences fall out of this:
+
+- Hosting in-cluster, behind the panel's own domain, is the only arrangement that
+  works — which is also the arrangement where your Service is not casually
+  reachable from outside.
+- Because the cookie is `httpOnly`, your plugin's frontend can never read it. It
+  rides along on requests and is exchanged for identity only by your backend
+  talking to the panel.
+
+::: warning Your backend receives a live session cookie
+Whichever identity mode you pick, the cookie reaches your service. It is a bearer
+credential for the calling user's 5Stack account. Do not log it, do not persist
+it, and do not forward it anywhere except the authorize endpoint. This is why
+plugins are admin-installed and why the panel treats a plugin backend as
+fully trusted code.
 :::
 
 ## Storing data
@@ -161,8 +221,8 @@ overwrite you.
 ## Machine-to-machine access
 
 If a game server or another service needs to reach your API without a browser
-session, forward-auth will not help — there is no user. Issue your own API key:
-generate it from an admin screen in your plugin, store it in your schema, and
-check it on a route excluded from the forward-auth ingress path.
+session, neither identity mode helps — there is no user and no cookie. Issue your
+own API key: generate it from an admin screen in your plugin, store it in your
+schema, and check it on a route excluded from the session check.
 
 Keep those routes narrow and separate from the session-authenticated ones.

plugins/components.md

@@ -176,7 +176,7 @@ match the panel's versions:
 
 ::: info
 `class-variance-authority` is a peer dependency of `@5stack/ui` but is not in the
-hello-world sample, because nothing currently exported from the package uses it.
+example plugin, because nothing currently exported from the package uses it.
 The moment you copy in a `cva`-based component — or the official components land
 — you need it. Adding it up front costs nothing.
 :::

plugins/deploying.md

@@ -72,9 +72,10 @@ entry, which helps — but do not rely on it in place of correct headers.
 Any static host works: nginx in a container, an object-storage bucket behind a
 CDN, or a static-site host.
 
-Serving from a **subdomain of the panel** (`myplugin.panel.example.com`) is the
-simplest arrangement, because it keeps the 5Stack session cookie same-site for
-any backend calls. See [Backend & Auth](/plugins/backend).
+If you have a backend, serving from a **subdomain of the panel**
+(`myplugin.panel.example.com`) is required, not just convenient — the 5Stack
+session cookie is `SameSite=Lax` and never reaches an unrelated domain, so
+identity is unavailable there. See [Backend & Auth](/plugins/backend).
 
 A minimal container:
 
@@ -101,15 +102,16 @@ the panel repo under `custom/<name>/` can be applied with:
 ```
 
 The inventory plugin is laid out this way — two ingresses on one host, `/api` to
-the backend with the forward-auth annotations and `/` to the static frontend.
-Its `k8s/` directory is a working template. See also
+the backend and `/` to the static frontend. Keep the backend a `ClusterIP`
+Service so the ingress is its only route in. Its `k8s/` directory is a working
+template. See also
 [Custom Kubernetes](/advanced/custom-k8s).
 
 ## Register it
 
-In the panel, go to **Settings → Application → Custom Pages**.
+In the panel, go to **Settings → Application → Plugins**.
 
-1. Make sure the **Custom Pages** master switch is enabled.
+1. Make sure the **Plugins** master switch is enabled.
 2. **Add**, paste your base URL (e.g. `https://myplugin.example.com`).
 3. Press **Detect**. The panel fetches `5stack-plugin.json` and fills in the
    name, slug, icon, remote entry, scope, module, and required role.

plugins/getting-started.md

@@ -1,12 +1,12 @@
 # Getting Started
 
 The fastest path to a working plugin is to copy the
-[hello-world sample](https://github.com/5stackgg/5stack-plugin-hello-world). It
+[example plugin](https://github.com/5stackgg/5stack-example-plugin). It
 is deliberately tiny — one component, one manifest, one Vite config — and it is
 already wired for everything described in this section.
 
 ```sh
-git clone https://github.com/5stackgg/5stack-plugin-hello-world my-plugin
+git clone https://github.com/5stackgg/5stack-example-plugin my-plugin
 cd my-plugin
 rm -rf .git && git init
 npm install
@@ -83,7 +83,7 @@ npm run build
 npx vite preview   # serves dist/ with cors enabled
 ```
 
-Then register `http://localhost:4173` as a Custom Page in your dev panel. See
+Then register `http://localhost:4173` as a plugin in your dev panel. See
 [Deploying](/plugins/deploying) for the CORS and cache headers this needs.
 
 ## Write your page
@@ -120,9 +120,9 @@ role check is never sufficient on its own.
 npm run build   # -> dist/remoteEntry.js in assets/, plus dist/5stack-plugin.json
 ```
 
-Host `dist/`, then in the panel go to **Settings → Application → Custom Pages →
+Host `dist/`, then in the panel go to **Settings → Application → Plugins →
 Add**, paste your base URL, press **Detect**, toggle **Enabled**, and save. Make
-sure the **Custom Pages** master switch is on.
+sure the **Plugins** master switch is on.
 
 Your page is now in the sidebar at `/apps/<slug>`.
 

plugins/index.md

@@ -1,6 +1,6 @@
 # Plugin Development
 
-Plugins — called **Custom Pages** in the panel UI — let you run your own web app
+Plugins let you run your own web app
 **inside 5Stack**. Same sidebar, same header, same theme, same login. Your app is
 not part of 5Stack and does not require a fork or a rebuild of the panel.
 
@@ -11,8 +11,8 @@ remote. The panel loads it at runtime and mounts it on a native route,
 - **No iframe.** Your component runs inside the panel's own Vue app, sharing its
   Vue instance, its router, and its styling.
 - **No second login.** The panel hands you the authenticated user. If you have a
-  backend, it sits behind 5Stack forward-auth instead of running its own Steam
-  OpenID flow.
+  backend, it exchanges the session cookie the browser already sends for a
+  verified identity, instead of running its own Steam OpenID flow.
 - **Native look.** The shared `@5stack/ui` Tailwind preset and design tokens mean
   your UI follows the operator's live branding automatically.
 - **No panel rebuild.** Plugins live in a database registry. An admin adds a URL;
@@ -31,9 +31,9 @@ SwiftlyS2 or CounterStrikeSharp plugins on a game server, see
    Federation remote. The build emits `dist/assets/remoteEntry.js`.
 2. You ship a manifest, `5stack-plugin.json`, at the root of that same build.
 3. You host `dist/` somewhere the panel's users can reach.
-4. An admin pastes your URL into **Settings → Application → Custom Pages**, hits
+4. An admin pastes your URL into **Settings → Application → Plugins**, hits
    **Detect**, and enables it.
-5. The panel writes a row into its `custom_pages` registry. Every connected
+5. The panel writes a row into its plugin registry. Every connected
    client picks the new entry up over a live subscription, renders a sidebar
    item, and — when a user navigates to `/apps/<slug>` — fetches your
    `remoteEntry.js`, resolves your exposed module, and mounts it:
@@ -61,7 +61,11 @@ you call [your own backend](/plugins/backend).
 
 ::: info No sandbox
 A plugin is loaded into the panel's JavaScript context with no isolation. It can
-read the host's cookies and reach into its stores. `requiredRole` controls who
+reach into the host's stores and act as the logged-in user against any API the
+panel can reach, and its backend receives that user's live session cookie. (The
+cookie itself is `httpOnly`, so plugin JavaScript cannot read it directly — but
+that is a small consolation given everything else it can do.) `requiredRole`
+controls who
 *sees* the page, not what the code *can do*. There is also no integrity pinning
 on `remoteEntry.js` — the panel loads whatever the registered URL serves, so a
 compromised plugin host compromises the panel for every user until the page is
@@ -73,8 +77,8 @@ yours.
 
 | Repo | What it shows |
 | --- | --- |
-| [5stack-plugin-hello-world](https://github.com/5stackgg/5stack-plugin-hello-world) | The smallest complete plugin. Start here — copy it. |
-| [5stack-inventory-plugin](https://github.com/lukepolo/5stack-inventory-plugin) | A production plugin with a Fastify backend, Postgres, forward-auth, and a Kubernetes deployment. |
+| [5stack-example-plugin](https://github.com/5stackgg/5stack-example-plugin) | The smallest complete plugin. Start here — copy it. |
+| [5stack-inventory-plugin](https://github.com/lukepolo/5stack-inventory-plugin) | A production plugin with a Fastify backend, Postgres, session-cookie auth, and a Kubernetes deployment. |
 
 ## Next steps
 
@@ -86,5 +90,5 @@ yours.
 - [Styling](/plugins/styling) — Tailwind setup, design tokens, and the CSS
   pitfalls unique to runtime-injected styles.
 - [Components](/plugins/components) — what `@5stack/ui` actually gives you today.
-- [Backend & Auth](/plugins/backend) — forward-auth and talking to your own API.
+- [Backend & Auth](/plugins/backend) — verifying identity and talking to your own API.
 - [Deploying](/plugins/deploying) — hosting, CORS, caching, and registration.

plugins/manifest.md

@@ -4,7 +4,7 @@
 project's `public/` directory so Vite copies it to `dist/5stack-plugin.json`,
 where it is served from the root of your build.
 
-An admin pastes your base URL into **Settings → Application → Custom Pages →
+An admin pastes your base URL into **Settings → Application → Plugins →
 Detect**, the panel fetches the manifest, and every field below is auto-filled
 into the registration form.
 
@@ -102,8 +102,8 @@ is in [Backend & Auth](/plugins/backend#roles).
 
 ::: warning `requiredRole` is visibility, not security
 It controls whether the sidebar entry and the route render. It does not protect
-your data. Anything sensitive must be enforced by your own backend against the
-forward-auth headers — see [Backend & Auth](/plugins/backend).
+your data. Anything sensitive must be re-checked by your own backend against a
+verified identity — see [Backend & Auth](/plugins/backend).
 :::
 
 ## Serving it

plugins/module-federation.md

@@ -78,7 +78,7 @@ Two rules follow.
 
 **Only list what you actually import.** Federation builds a shared entry chunk for
 every key in `shared`, and a package that is listed but not installed fails the
-build. The hello-world sample lists six because it imports six. Add `pinia` or
+build. The example plugin lists six because it imports six. Add `pinia` or
 `vue-router` to both `shared` and your `package.json` only once you actually use
 them.