Add auth on games

Start by reading apps/client/src/server.ts, then trace how the website fetches the manifest and environment in apps/website/src/manifest.ts and apps/website/src/env.ts. The issue proposes authentication across the client and website, with game server identity as a possible follow-up; agree on scope and flow before implementation. Done means configured users are authenticated and access rules protect game files, while unauthenticated behavior remains unchanged when auth is disabled.

Which app is this feature request for?

other

Feature

Involves client, website and server.

The loader has no access control. Anyone who can reach the client URL can load the game:

• The client serves /manifest, /env and /game/* with no authentication (server.ts#L87, #L100, #L112).
• /env returns every NANOFORGE_* environment variable, prefix stripped (env.ts#L1-L8).
• The website (apps/website) fetches the manifest and downloads every game file into OPFS without identifying the user.
• The game server (apps/server) forks the game's main.js and never learns who the connecting players are.

So developers can't:

• limit a game to certain users (closed beta, paid access, internal testers);
• reuse an existing identity provider (Google, GitHub, Discord, Keycloak, a studio's own SSO, etc.);
• get a trusted user identity inside the game or on the game server.

The goal: an optional authentication step in the loader, configured by the developer, that checks the user through SSO / OAuth2 before any game file is served and denies everyone else. When nothing is configured, behavior stays exactly as it is today.

Ideal solution or implementation

Support OpenID Connect / OAuth2 (Authorization Code + PKCE) with any provider, configured through CLI options or environment variables.

Phase 1: client (apps/client)

• Options, for example:

  --auth-issuer <url>           OIDC issuer (discovery via /.well-known/openid-configuration)
  --auth-client-id <id>
  --auth-client-secret <secret> (optional, confidential clients)
  --auth-scopes <scopes>        default: "openid profile email"
  --auth-allow <rule>           allowed emails / domains / groups / roles claim
  

  Custom (non-OIDC) OAuth2 providers could be supported by setting the authorize, token and userinfo URLs explicitly.
• Routes /auth/login (redirects to the provider), /auth/callback (exchanges the code, validates the ID token), /auth/logout and /auth/me.
• Session stored in an HttpOnly, Secure, SameSite cookie (signed or encrypted).
• Route guard on /manifest, /env and /game/*: 401 without a valid session, 403 if the user doesn't match --auth-allow. The website shell (/, static assets) stays public so it can show a login screen.
• Allow rule checked on the server side (claims, email domain, group or role membership), plus a hook for custom rules (e.g. a function exported from the game directory, or a webhook).
• Auth secrets never appear in /env (another prefix than NANOFORGE_, or filtered out).
• With no auth option set, the client behaves as today (test).

Phase 2: website (apps/website)

• On 401 from /manifest or /env: a "Sign in" screen that redirects to /auth/login. On 403: an "Access denied" screen.
• The authenticated user's identity (id, name, email, claims) is available to the game, e.g. through IGameOptions or next to the env.
• The OPFS game cache is cleared or scoped per user on logout, so files downloaded by one user aren't reused by another user on the same browser.

Phase 3: game server (apps/server)

• The website passes a short-lived access token or ID token to the game server when it connects.
• A helper checks that token against the same issuer (JWKS), so the game server can trust player identities.

Auth requirements for every phase: state and nonce parameters, PKCE, token signature checked against JWKS, a redirect URI allowlist, client secrets kept out of /env, HTTPS in production (the client already supports --cert / --key, server.ts#L24-L25).

Alternative solutions or implementations

• Basic auth or a shared access key (--password, NANOFORGE_ACCESS_KEY): very easy to build, and enough for private previews. But there are no per-user identities, and revoking one person's access isn't possible.
• Delegating auth to a reverse proxy (oauth2-proxy, Cloudflare Access, Authelia): works today with no code changes. But it has to be set up outside NanoForge, and the game never receives the user's identity. It would still help to document it as the "no built-in auth" option.
• Custom SSO only through a plugin/hook API: the loader calls a function supplied by the developer to authorize each request. Flexible, but every developer would have to write their own OAuth flow.

Other context

• Relevant files: apps/client/src/server.ts (routes), apps/client/src/env.ts, apps/website/src/manifest.ts, apps/website/src/env.ts, apps/website/src/cache/cache.ts, apps/website/src/types/game.type.ts, apps/server/src/server.ts.
• The per-file game cache this issue referred to is done (#121, merged). The cached files still have to be scoped per user or invalidated when the user changes (phase 2).

Open questions (not recorded, ask the team):

• Is phase 3 (game server) part of this issue, or a follow-up issue?
• Configuration through CLI options, environment variables, or both? And how does nf start pass them to the client?
• Which custom-rule hook: a function from the game directory, a webhook, or none at first?