@crowdedkingdoms/crowdyjs 6.1.1 → 7.1.0

package/MIGRATION.md

@@ -1,3 +1,58 @@
+# CrowdyJS v7 — Overworld portals & app-scoped tokens (BREAKING)
+
+v7 splits the single app-agnostic game token into two credentials and makes
+gameplay require an **app-scoped token**. This is a breaking change requiring
+servers on the matching release (management-api + game-api + Buddy with the
+app-scoped-token feature).
+
+**The two credential kinds**
+
+- **Identity SESSION token** — returned by `client.auth.login()` / `register()`.
+  It talks to the **Management API only** (account, studio admin, and minting
+  app tokens). It is **no longer valid for gameplay**: the Game API and Buddy
+  reject it. Never hand it to a game stack.
+- **App-scoped GAMEPLAY token** — short-lived (default ~30 min), confined to one
+  app. Minted from a session token via the portal flow; used against that app's
+  Game API + realtime surface.
+
+**What breaks**
+
+- Driving `client.udp`, `client.world(appId)`, `serverWithLeastClients`,
+  `connectUdpProxy`, world reads/writes, etc. with a plain login token now fails
+  (`APP_TOKEN_REQUIRED` on `udpNotifications`; `FORBIDDEN`/`SCOPE_MISSING` on
+  HTTP). You must obtain an app token first.
+- A single client can no longer be both your identity client and your game
+  client. Use the two-client pattern: an Overworld/identity client (holds the
+  session token) and a per-game client (holds that game's app token).
+
+**New: `client.portal`**
+
+```ts
+// Native / same-origin: mint directly with the session token.
+const appToken = await overworld.portal.mintAppToken(appId);
+const game = createCrowdyClient({ httpUrl: appToken.gameApiUrl!, wsUrl: appToken.gameApiWsUrl!,
+  managementUrl, tokenStore: new BrowserLocalStorageTokenStore('crowdyjs:token:' + appId) });
+game.setToken(appToken.token);
+
+// Browser cross-origin handoff (OAuth2 Authorization Code + PKCE):
+//   game origin, on "enter":
+const url = await game.portal.beginEntry({ appId, authorizeUrl: 'https://overworld.example.com/authorize',
+  redirectUri: location.origin + location.pathname });
+location.assign(url);
+//   Overworld /authorize page (holds the session token):
+location.assign(await overworld.portal.handleAuthorizeRequest());
+//   game origin, on callback boot:
+const token = await game.portal.completeEntry(); // exchanges code+verifier, stores app token
+//   keep playing past expiry without re-portaling:
+await game.portal.refresh();
+```
+
+The session token never reaches the game origin — only the app token does. New
+realtime `RealtimeConnectionEvent` codes: `APP_TOKEN_REQUIRED`,
+`APP_SCOPE_MISMATCH`. New `UdpErrorCode`: `TOKEN_EXPIRED`.
+
+---
+
 # CrowdyJS — npm org rename (v6 version line kept)
 
 The package moved to the **`@crowdedkingdoms`** npm organization. The version line

package/README.md

@@ -260,6 +260,52 @@ The key parameter is optional and trailing, so it's safe to omit. Requires a ser
 - `client.session.restore()` reads from the configured `tokenStore`. `BrowserLocalStorageTokenStore` is provided; bring your own for SSR or Node usage.
 - A single `AuthState` is observed by both the HTTP client and the realtime socket, so HTTP and WebSocket auth can never drift.
 
+## Overworld portals & app-scoped tokens (v7)
+
+As of v7 gameplay requires an **app-scoped token**, not the login token. Login
+returns an **identity session token** (Management API only — account, studio
+admin, and minting); each game is entered with a short-lived token confined to
+that one app, so a game stack never receives the player's full session.
+
+Use two clients: an Overworld/identity client (session token) and a per-game
+client (app token), sharing only the Management URL.
+
+```ts
+// Overworld/identity client
+const overworld = createCrowdyClient({ managementUrl, tokenStore: new BrowserLocalStorageTokenStore('crowdyjs:session') });
+await overworld.auth.login({ email, password });
+
+// Native / same-origin: mint directly, then build a game client.
+const t = await overworld.portal.mintAppToken(appId);
+const game = createCrowdyClient({ httpUrl: t.gameApiUrl!, wsUrl: t.gameApiWsUrl!, managementUrl,
+  tokenStore: new BrowserLocalStorageTokenStore('crowdyjs:app:' + appId) });
+game.setToken(t.token);
+game.world(appId).subscribe({ actorUpdate: (n) => { /* ... */ } });
+```
+
+Browser cross-origin handoff is OAuth2 Authorization Code + PKCE — the verifier
+never leaves the game origin:
+
+```ts
+// Game origin, on "enter": redirect to the Overworld authorize page.
+location.assign(await game.portal.beginEntry({
+  appId, authorizeUrl: 'https://overworld.example.com/authorize',
+  redirectUri: location.origin + location.pathname,
+}));
+
+// Overworld /authorize page (holds the session token):
+location.assign(await overworld.portal.handleAuthorizeRequest());
+
+// Game origin, on callback boot: exchange code+verifier -> app token (stored).
+const entered = await game.portal.completeEntry();
+// Keep playing past expiry without re-portaling (same app):
+await game.portal.refresh();
+```
+
+Game-to-game routes through the Overworld for a fresh per-game token. New
+realtime codes: `APP_TOKEN_REQUIRED`, `APP_SCOPE_MISMATCH`; new `UdpErrorCode`:
+`TOKEN_EXPIRED`. See [MIGRATION.md](MIGRATION.md) for the full v7 breaking guide.
+
 ## Surface scope & security
 
 As of v6 (completed in v6.1), CrowdyJS wraps the **full** management-api + game-api

package/dist/crowdy-client.d.ts

@@ -29,6 +29,7 @@ import { WorldClient } from './world.js';
 import { AuthAPI } from './domains/auth.js';
 import { UsersAPI } from './domains/users.js';
 import { AppsAPI } from './domains/apps.js';
+import { PortalAPI, type PkceStore } from './domains/portal.js';
 import { PlatformAPI } from './domains/platform.js';
 import { OrganizationsAPI } from './domains/organizations.js';
 import { AppAccessAPI } from './domains/appAccess.js';
@@ -82,6 +83,13 @@ export interface CrowdyClientConfig {
     tokenStore?: TokenStore;
     /** Optional logger for SDK diagnostics (request/realtime lifecycle). */
     logger?: CrowdyLogger;
+    /**
+     * Optional storage for the PKCE verifier across the portal redirect round-trip
+     * (`client.portal.beginEntry` -> `completeEntry`). Defaults to a
+     * sessionStorage-backed store in the browser; supply your own for SSR, native,
+     * or tests where sessionStorage is unavailable.
+     */
+    pkceStore?: PkceStore;
     /** Realtime (WebSocket) tuning for reconnect backoff and `...AndWait` timeouts. */
     realtime?: {
         /** Max reconnect attempts before giving up (default tuned for browsers). */
@@ -109,6 +117,12 @@ export declare class CrowdyClient {
     readonly users: UsersAPI;
     /** App discovery + routing (which game-api serves a given app). */
     readonly apps: AppsAPI;
+    /**
+     * Overworld portal: mint/exchange/refresh app-scoped gameplay tokens and the
+     * PKCE browser handoff. Identity session token mints; games receive only an
+     * app token.
+     */
+    readonly portal: PortalAPI;
     /** Public platform discovery (shared game-api URL, free app quota). */
     readonly platform: PlatformAPI;
     /** Organizations, members, RBAC roles, and org API tokens (studio admin). */

package/dist/crowdy-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"crowdy-client.d.ts","sourceRoot":"","sources":["../src/crowdy-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"crowdy-client.d.ts","sourceRoot":"","sources":["../src/crowdy-client.ts"],"names":[],"mappings":"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"}

package/dist/crowdy-client.js

@@ -27,6 +27,7 @@ import { WorldClient } from './world.js';
 import { AuthAPI } from './domains/auth.js';
 import { UsersAPI } from './domains/users.js';
 import { AppsAPI } from './domains/apps.js';
+import { PortalAPI } from './domains/portal.js';
 import { PlatformAPI } from './domains/platform.js';
 import { OrganizationsAPI } from './domains/organizations.js';
 import { AppAccessAPI } from './domains/appAccess.js';
@@ -56,20 +57,19 @@ export class CrowdyClient {
         this.session = new AuthState(config.tokenStore);
         this.graphql = new GraphQLClient({
             httpUrl: config.httpUrl,
-            graphqlEndpoint: config.graphqlEndpoint,
+            graphqlEndpoint: config.graphqlEndpoint ?? toGraphqlEndpoint(config.httpUrl, 'graphql'),
             timeout: config.timeout,
             logger: config.logger,
         }, this.session);
         this.realtime = new SubscriptionManager({
             wsUrl: config.wsUrl,
-            wsEndpoint: config.wsEndpoint,
+            wsEndpoint: config.wsEndpoint ?? toGraphqlEndpoint(config.wsUrl, 'graphql'),
             logger: config.logger,
             ...config.realtime,
         }, this.session);
         const managementGraphqlEndpoint = config.managementGraphqlEndpoint ??
-            (config.managementUrl
-                ? `${config.managementUrl.replace(/\/$/, '')}/graphql`
-                : config.graphqlEndpoint);
+            toGraphqlEndpoint(config.managementUrl, 'graphql') ??
+            config.graphqlEndpoint;
         // Management-api client. Falls back to game-api endpoint if the caller
         // hasn't configured `managementUrl` yet (single-endpoint legacy mode).
         this.management = new GraphQLClient({
@@ -81,6 +81,7 @@ export class CrowdyClient {
         this.auth = new AuthAPI(this.management, this.session);
         this.users = new UsersAPI(this.management);
         this.apps = new AppsAPI(this.management);
+        this.portal = new PortalAPI(this.management, this.session, config.pkceStore);
         this.platform = new PlatformAPI(this.management);
         this.organizations = new OrganizationsAPI(this.management);
         this.appAccess = new AppAccessAPI(this.management);
@@ -144,3 +145,16 @@ export class CrowdyClient {
 export function createCrowdyClient(config = {}) {
     return new CrowdyClient(config);
 }
+/**
+ * Normalize a base URL into a GraphQL endpoint. Accepts either a base origin
+ * (`https://game.example.com`) or a full endpoint already ending in `/graphql`
+ * (the historical form some callers pass as `httpUrl`/`wsUrl`), so the portal's
+ * `gameApiUrl` (a base URL) is usable directly. Returns undefined for empty input.
+ */
+function toGraphqlEndpoint(url, suffix) {
+    const trimmed = url?.trim();
+    if (!trimmed)
+        return undefined;
+    const noSlash = trimmed.replace(/\/$/, '');
+    return noSlash.endsWith(`/${suffix}`) ? noSlash : `${noSlash}/${suffix}`;
+}

package/dist/domains/portal.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Overworld portal: the client side of app-scoped tokens.
+ *
+ * Two distinct credential kinds replace the old single app-agnostic token:
+ *   - an identity SESSION token (from `client.auth.login` / `register`) that
+ *     talks to the Management API and is the ONLY thing that can mint app
+ *     tokens. Never send it to a game stack.
+ *   - short-lived, app-scoped GAMEPLAY tokens, one per game, used against that
+ *     game's Game API + realtime surface.
+ *
+ * Typical wiring is two `CrowdyClient`s sharing nothing but the same Management
+ * URL: an "Overworld"/identity client holding the session token, and a per-game
+ * client whose token store holds that game's app token.
+ *
+ * Browser handoff (cross-origin) is an OAuth2 Authorization-Code + PKCE flow:
+ *   1. game origin: `beginEntry()` -> redirect the player to the Overworld
+ *      `/authorize` page carrying a PKCE challenge + the game's redirect URI.
+ *   2. Overworld origin (holds the session): `handleAuthorizeRequest()` ->
+ *      mints a one-time code and redirects back to the game.
+ *   3. game origin: `completeEntry()` -> exchanges the code (+ the PKCE verifier
+ *      it kept locally) for an app token and stores it.
+ *
+ * Native / same-origin callers can skip the redirect dance and call
+ * `mintAppToken(appId)` directly with a session token.
+ */
+import type { GraphQLClient } from '../client.js';
+import type { SessionStore } from '../session.js';
+export interface AppTokenResponse {
+    /** Opaque app-scoped gameplay token. Send to the app's Game API as a Bearer. */
+    token: string;
+    gameTokenId: string;
+    /** The app this token is confined to (decimal string). */
+    appId: string;
+    /** ISO-8601 UTC expiry. Refresh (same app) or re-portal before this. */
+    expiresAt: string;
+    /** Base HTTPS URL of the Game API serving this app (null if unrouted). */
+    gameApiUrl: string | null;
+    /** WebSocket URL of the Game API serving this app. */
+    gameApiWsUrl: string | null;
+    /** Browser launch URL for this app, if configured. */
+    launchUrl: string | null;
+}
+export interface PortalAuthorizationCode {
+    code: string;
+    redirectUri: string;
+    expiresAt: string;
+}
+/** Persists the PKCE verifier across the cross-origin redirect round-trip. */
+export interface PkceStore {
+    get(state: string): string | null | Promise<string | null>;
+    set(state: string, verifier: string): void | Promise<void>;
+    remove(state: string): void | Promise<void>;
+}
+/** Default PKCE store backed by sessionStorage; no-op when unavailable (SSR). */
+export declare class BrowserSessionPkceStore implements PkceStore {
+    private readonly prefix;
+    constructor(prefix?: string);
+    private ss;
+    get(state: string): string | null;
+    set(state: string, verifier: string): void;
+    remove(state: string): void;
+}
+export interface BeginEntryParams {
+    /** Target app id (decimal string). */
+    appId: string;
+    /** The Overworld identity origin's authorize page, e.g. `https://overworld.example.com/authorize`. */
+    authorizeUrl: string;
+    /** Where the Overworld should send the player back (this game's callback). */
+    redirectUri: string;
+    /** Optional CSRF/correlation state; one is generated if omitted. */
+    state?: string;
+}
+export declare class PortalAPI {
+    private readonly management;
+    private readonly session;
+    private readonly pkceStore;
+    constructor(management: GraphQLClient, session: SessionStore, pkceStore?: PkceStore);
+    /**
+     * Native/direct mint: exchange the caller's identity session token for an
+     * app-scoped gameplay token. Returns the token; it is NOT stored on this
+     * client (build a per-game client with it). Free/open apps auto-grant access;
+     * paid apps require an existing entitlement.
+     */
+    mintAppToken(appId: string): Promise<AppTokenResponse>;
+    /**
+     * Overworld/identity side: mint a one-time authorization code for a target
+     * app, bound to the destination game's PKCE challenge + redirect URI.
+     * Requires the identity session token.
+     */
+    createAuthorizationCode(params: {
+        appId: string;
+        codeChallenge: string;
+        codeChallengeMethod?: string;
+        redirectUri: string;
+    }): Promise<PortalAuthorizationCode>;
+    /**
+     * Destination-game side: exchange a one-time code (+ PKCE verifier) for an app
+     * token and store it on this client's session so subsequent Game API calls are
+     * authenticated. Public — no session token required.
+     */
+    exchangeCode(code: string, codeVerifier?: string): Promise<AppTokenResponse>;
+    /**
+     * Same-app refresh: rotate the current app token for a fresh one (extended
+     * TTL) and store it. Call before expiry to keep playing without bouncing
+     * through the Overworld. Requires the current app token on this session.
+     */
+    refresh(): Promise<AppTokenResponse>;
+    /**
+     * Destination-game side, step 1: generate a PKCE pair, persist the verifier,
+     * and return the Overworld authorize URL to navigate to. The caller does
+     * `window.location.assign(url)`.
+     */
+    beginEntry(params: BeginEntryParams): Promise<string>;
+    /**
+     * Overworld/identity side: handle an incoming `/authorize` request. Reads the
+     * game's params from the URL, mints a code with the session token, and returns
+     * the URL to redirect the player back to (carrying `code` + `state`).
+     */
+    handleAuthorizeRequest(search?: string): Promise<string>;
+    /**
+     * Destination-game side, step 3: read `code` + `state` from the callback URL,
+     * load the stored verifier, exchange for an app token, and store it. Returns
+     * null when there is no `code` param (so it's safe to call unconditionally on
+     * boot).
+     */
+    completeEntry(search?: string): Promise<AppTokenResponse | null>;
+}
+//# sourceMappingURL=portal.d.ts.map

package/dist/domains/portal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"portal.d.ts","sourceRoot":"","sources":["../../src/domains/portal.ts"],"names":[],"mappings":"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"}

package/dist/domains/portal.js

@@ -0,0 +1,167 @@
+/**
+ * Overworld portal: the client side of app-scoped tokens.
+ *
+ * Two distinct credential kinds replace the old single app-agnostic token:
+ *   - an identity SESSION token (from `client.auth.login` / `register`) that
+ *     talks to the Management API and is the ONLY thing that can mint app
+ *     tokens. Never send it to a game stack.
+ *   - short-lived, app-scoped GAMEPLAY tokens, one per game, used against that
+ *     game's Game API + realtime surface.
+ *
+ * Typical wiring is two `CrowdyClient`s sharing nothing but the same Management
+ * URL: an "Overworld"/identity client holding the session token, and a per-game
+ * client whose token store holds that game's app token.
+ *
+ * Browser handoff (cross-origin) is an OAuth2 Authorization-Code + PKCE flow:
+ *   1. game origin: `beginEntry()` -> redirect the player to the Overworld
+ *      `/authorize` page carrying a PKCE challenge + the game's redirect URI.
+ *   2. Overworld origin (holds the session): `handleAuthorizeRequest()` ->
+ *      mints a one-time code and redirects back to the game.
+ *   3. game origin: `completeEntry()` -> exchanges the code (+ the PKCE verifier
+ *      it kept locally) for an app token and stores it.
+ *
+ * Native / same-origin callers can skip the redirect dance and call
+ * `mintAppToken(appId)` directly with a session token.
+ */
+import { parse } from 'graphql';
+import { generatePkcePair, generateState } from '../pkce.js';
+/** Default PKCE store backed by sessionStorage; no-op when unavailable (SSR). */
+export class BrowserSessionPkceStore {
+    constructor(prefix = 'crowdyjs:pkce:') {
+        this.prefix = prefix;
+    }
+    ss() {
+        return typeof sessionStorage === 'undefined' ? null : sessionStorage;
+    }
+    get(state) {
+        return this.ss()?.getItem(this.prefix + state) ?? null;
+    }
+    set(state, verifier) {
+        this.ss()?.setItem(this.prefix + state, verifier);
+    }
+    remove(state) {
+        this.ss()?.removeItem(this.prefix + state);
+    }
+}
+const APP_TOKEN_FIELDS = 'token gameTokenId appId expiresAt gameApiUrl gameApiWsUrl launchUrl';
+const MintAppTokenDocument = parse(`mutation MintAppToken($input: MintAppTokenInput!) { mintAppToken(input: $input) { ${APP_TOKEN_FIELDS} } }`);
+const CreatePortalAuthorizationCodeDocument = parse(`mutation CreatePortalAuthorizationCode($input: CreatePortalAuthorizationCodeInput!) { createPortalAuthorizationCode(input: $input) { code redirectUri expiresAt } }`);
+const ExchangePortalCodeDocument = parse(`mutation ExchangePortalCode($input: ExchangePortalCodeInput!) { exchangePortalCode(input: $input) { ${APP_TOKEN_FIELDS} } }`);
+const RefreshAppTokenDocument = parse(`mutation RefreshAppToken { refreshAppToken { ${APP_TOKEN_FIELDS} } }`);
+export class PortalAPI {
+    constructor(management, session, pkceStore = new BrowserSessionPkceStore()) {
+        this.management = management;
+        this.session = session;
+        this.pkceStore = pkceStore;
+    }
+    /**
+     * Native/direct mint: exchange the caller's identity session token for an
+     * app-scoped gameplay token. Returns the token; it is NOT stored on this
+     * client (build a per-game client with it). Free/open apps auto-grant access;
+     * paid apps require an existing entitlement.
+     */
+    async mintAppToken(appId) {
+        const data = await this.management.request(MintAppTokenDocument, {
+            input: { appId },
+        });
+        return data.mintAppToken;
+    }
+    /**
+     * Overworld/identity side: mint a one-time authorization code for a target
+     * app, bound to the destination game's PKCE challenge + redirect URI.
+     * Requires the identity session token.
+     */
+    async createAuthorizationCode(params) {
+        const data = await this.management.request(CreatePortalAuthorizationCodeDocument, { input: params });
+        return data.createPortalAuthorizationCode;
+    }
+    /**
+     * Destination-game side: exchange a one-time code (+ PKCE verifier) for an app
+     * token and store it on this client's session so subsequent Game API calls are
+     * authenticated. Public — no session token required.
+     */
+    async exchangeCode(code, codeVerifier) {
+        const data = await this.management.request(ExchangePortalCodeDocument, {
+            input: { code, codeVerifier },
+        });
+        this.session.setToken(data.exchangePortalCode.token);
+        return data.exchangePortalCode;
+    }
+    /**
+     * Same-app refresh: rotate the current app token for a fresh one (extended
+     * TTL) and store it. Call before expiry to keep playing without bouncing
+     * through the Overworld. Requires the current app token on this session.
+     */
+    async refresh() {
+        const data = await this.management.request(RefreshAppTokenDocument, {});
+        this.session.setToken(data.refreshAppToken.token);
+        return data.refreshAppToken;
+    }
+    // ----- Browser PKCE redirect helpers -------------------------------------
+    /**
+     * Destination-game side, step 1: generate a PKCE pair, persist the verifier,
+     * and return the Overworld authorize URL to navigate to. The caller does
+     * `window.location.assign(url)`.
+     */
+    async beginEntry(params) {
+        const state = params.state ?? generateState();
+        const pkce = await generatePkcePair();
+        await this.pkceStore.set(state, pkce.verifier);
+        const url = new URL(params.authorizeUrl);
+        url.searchParams.set('app_id', params.appId);
+        url.searchParams.set('code_challenge', pkce.challenge);
+        url.searchParams.set('code_challenge_method', pkce.method);
+        url.searchParams.set('redirect_uri', params.redirectUri);
+        url.searchParams.set('state', state);
+        return url.toString();
+    }
+    /**
+     * Overworld/identity side: handle an incoming `/authorize` request. Reads the
+     * game's params from the URL, mints a code with the session token, and returns
+     * the URL to redirect the player back to (carrying `code` + `state`).
+     */
+    async handleAuthorizeRequest(search) {
+        const params = new URLSearchParams(search ?? defaultSearch());
+        const appId = params.get('app_id');
+        const codeChallenge = params.get('code_challenge');
+        const redirectUri = params.get('redirect_uri');
+        const state = params.get('state') ?? '';
+        const codeChallengeMethod = params.get('code_challenge_method') ?? 'S256';
+        if (!appId || !codeChallenge || !redirectUri) {
+            throw new Error('authorize request missing app_id, code_challenge, or redirect_uri');
+        }
+        const result = await this.createAuthorizationCode({
+            appId,
+            codeChallenge,
+            codeChallengeMethod,
+            redirectUri,
+        });
+        const back = new URL(result.redirectUri);
+        back.searchParams.set('code', result.code);
+        if (state)
+            back.searchParams.set('state', state);
+        return back.toString();
+    }
+    /**
+     * Destination-game side, step 3: read `code` + `state` from the callback URL,
+     * load the stored verifier, exchange for an app token, and store it. Returns
+     * null when there is no `code` param (so it's safe to call unconditionally on
+     * boot).
+     */
+    async completeEntry(search) {
+        const params = new URLSearchParams(search ?? defaultSearch());
+        const code = params.get('code');
+        if (!code)
+            return null;
+        const state = params.get('state') ?? '';
+        const verifier = (await this.pkceStore.get(state)) ?? undefined;
+        const token = await this.exchangeCode(code, verifier);
+        if (state)
+            await this.pkceStore.remove(state);
+        return token;
+    }
+}
+function defaultSearch() {
+    const loc = globalThis.location;
+    return loc?.search ?? '';
+}