@crowdedkingdoms/crowdyjs 6.1.1 → 7.0.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 } from './domains/portal.js';
 import { PlatformAPI } from './domains/platform.js';
 import { OrganizationsAPI } from './domains/organizations.js';
 import { AppAccessAPI } from './domains/appAccess.js';
@@ -109,6 +110,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';
@@ -81,6 +82,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);
         this.platform = new PlatformAPI(this.management);
         this.organizations = new OrganizationsAPI(this.management);
         this.appAccess = new AppAccessAPI(this.management);

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 ?? '';
+}

package/dist/generated/graphql.d.ts

@@ -392,6 +392,24 @@ export declare enum AppStatus {
     /** Published and purchasable/playable; eligible for the public marketplace when visibility=PUBLIC. */
     Live = "LIVE"
 }
+/** A short-lived, app-scoped gameplay token (Overworld portal). Confined to a single app: usable only against that app's Game API + Buddy realtime surface (plus read-only `me` and same-app `refreshAppToken`). It CANNOT perform management operations and CANNOT mint tokens for other apps, so a game stack that receives it never gets the player's full identity session. */
+export type AppTokenResponse = {
+    __typename?: 'AppTokenResponse';
+    /** The app this token is confined to, as a String. */
+    appId: Scalars['String']['output'];
+    /** ISO-8601 UTC expiry. Call `refreshAppToken` (same app) before this, or re-portal through the Overworld for a different app. */
+    expiresAt: Scalars['String']['output'];
+    /** Base HTTPS URL of the Game API that serves this app (null if the app has no dedicated/shared game-api route yet). */
+    gameApiUrl: Maybe<Scalars['String']['output']>;
+    /** WebSocket URL of the Game API that serves this app (wss://), for realtime subscriptions. */
+    gameApiWsUrl: Maybe<Scalars['String']['output']>;
+    /** Identifier of the underlying game_token row, as a String. */
+    gameTokenId: Scalars['String']['output'];
+    /** Browser launch URL for this app (where the player's browser plays it), if configured. */
+    launchUrl: Maybe<Scalars['String']['output']>;
+    /** Opaque app-scoped gameplay token. Send to the target app's Game API as `Authorization: Bearer <token>` (and in the realtime `connectionParams`). Do NOT send it to the Management API for anything other than `me`/`refreshAppToken`. */
+    token: Scalars['String']['output'];
+};
 /** Aggregate byte totals for one app over the requested window. All *Bytes fields are string counters (may exceed Int range). */
 export type AppUsageRollupRow = {
     __typename?: 'AppUsageRollupRow';
@@ -1728,6 +1746,17 @@ export type CreateOrganizationInput = {
     /** Unique URL slug; lowercase letters, numbers, and dashes only (1-128 characters). */
     slug: Scalars['String']['input'];
 };
+/** Input for createPortalAuthorizationCode: the Overworld (identity origin, holding the session token) mints a one-time code the destination game exchanges for an app token. Browser handoff path; pair with a PKCE verifier held by the destination game origin. */
+export type CreatePortalAuthorizationCodeInput = {
+    /** Numeric id of the target app the player is portaling into. */
+    appId: Scalars['BigInt']['input'];
+    /** PKCE code challenge (recommended). Base64url(SHA-256(verifier)) when method is S256. The destination game generates the verifier+challenge so the verifier never leaves its origin. */
+    codeChallenge: Scalars['String']['input'];
+    /** PKCE method: "S256" (default, recommended) or "plain". */
+    codeChallengeMethod?: InputMaybe<Scalars['String']['input']>;
+    /** Where to redirect the player after issuing the code. Must match the target app's configured launch_url origin when set. */
+    redirectUri: Scalars['String']['input'];
+};
 /** Create a runtime session. */
 export type CreateSessionInput = {
     /** The app (tenant) the session belongs to. */
@@ -1848,6 +1877,13 @@ export type EnvironmentUsageSummary = {
     /** Peak/average replication send rates. */
     replicationRates: UsageRatePeaks;
 };
+/** Input for exchangePortalCode: the destination game (public client) trades a one-time portal code for an app-scoped gameplay token. Public (the code + PKCE verifier authorize the call). */
+export type ExchangePortalCodeInput = {
+    /** The one-time authorization code received on the redirect. */
+    code: Scalars['String']['input'];
+    /** PKCE code verifier matching the challenge supplied when the code was created. Required when the code was created with a challenge. */
+    codeVerifier?: InputMaybe<Scalars['String']['input']>;
+};
 /** An org's free shared app slot quota usage. */
 export type FreeAppQuota = {
     __typename?: 'FreeAppQuota';
@@ -2860,6 +2896,11 @@ export type LoginUserInput = {
     /** Account password (min 8 characters). */
     password: Scalars['String']['input'];
 };
+/** Input for mintAppToken: directly mint an app-scoped gameplay token for the calling user (native/direct path, no browser redirect). */
+export type MintAppTokenInput = {
+    /** Numeric id of the app to mint a confined gameplay token for. Free/open apps are auto-granted access; paid apps require an existing entitlement (else FORBIDDEN). */
+    appId: Scalars['BigInt']['input'];
+};
 export type Mutation = {
     __typename?: 'Mutation';
     /** Liveness heartbeat for the authenticated user's actors in an app. Refreshes actors.updated_at for every actor row the user owns so the user stays host-eligible, then returns the freshly-elected host (same shape as the gameHost query) so a client can fold its poll and heartbeat into one round-trip. Call on an interval shorter than HOST_ACTOR_FRESHNESS_SECONDS. Only refreshes rows that already exist (created by Buddy on chunk entry); returns null when no fresh actors exist for the app. */
@@ -2910,6 +2951,8 @@ export type Mutation = {
     createOrgToken: OrgTokenWithSecret;
     /** Creates a new organization and makes the authenticated caller its owner (with full permissions). Requires a valid session token. */
     createOrganization: Organization;
+    /** Create a one-time, PKCE-bound portal authorization code (browser handoff). The Overworld identity origin (holding the SESSION token) calls this; redirect the player to the destination game carrying the code, which the game exchanges via exchangePortalCode. Requires a SESSION token. */
+    createPortalAuthorizationCode: PortalAuthorizationCode;
     /** Create a team. Whether the caller may create one is governed by the per-app team policy (app_group_policies: admin | member | anyone). The caller becomes the owner and is granted a system 'leader' role holding every team permission. New teams default to the app's default membership policy unless overridden. */
     createTeam: Group;
     /** Create a custom (non-system) team role granting the given team permission keys. Requires the 'manage_roles' team permission (app admins bypass). Permission keys must be valid team permission keys (group_permission_defs). */
@@ -2942,6 +2985,8 @@ export type Mutation = {
     destroyEnvironment: CksEnvironmentChangeOrder;
     /** Close the UDP proxy session and socket for this game token. Unsubscribing from udpNotifications does not disconnect; use this mutation (or rely on server inactivity timeout). */
     disconnectUdpProxy: Scalars['Boolean']['output'];
+    /** Exchange a one-time portal authorization code (with the matching PKCE verifier) for an app-scoped gameplay token. Public (the code + verifier authorize the call); called by the destination game at its own origin so the game never sees the player's session token. */
+    exchangePortalCode: AppTokenResponse;
     /** ADMIN/DESTRUCTIVE: revokes ALL of the target user’s sessions by deleting every game_token row, forcing re-authentication on every device. Returns true if at least one session was revoked. Requires a super-admin bearer game token (and the management API enabled). NOTE: management-owned in cks-game-api (throws ForbiddenException) — use cks-management-api. */
     forceLogoutUser: Scalars['Boolean']['output'];
     /** Create a directed relationship edge between two containers (the game model is a graph), with a relationship type and optional weight. Requires a valid token. */
@@ -3016,6 +3061,8 @@ export type Mutation = {
     logout: Scalars['Boolean']['output'];
     /** Ends every active session for the authenticated user (deletes all their game_tokens and records revocations). Requires a valid session token. Use logout to end only the current session. */
     logoutAllDevices: Scalars['Boolean']['output'];
+    /** Mint a short-lived, app-scoped gameplay token for the calling user (native/direct path; no browser redirect). Requires an identity SESSION token (app tokens cannot mint). Free/open apps auto-grant access; paid apps require an existing entitlement (else FORBIDDEN). Side effect: may create an app_user_access row on the app's free default tier. */
+    mintAppToken: AppTokenResponse;
     /** Publishes an app to the shared game-api environment. Free under the org's app-slot quota (result.free = true); beyond the quota, publish still succeeds and hourly usage is debited from the org wallet. Requires the 'manage_apps' permission on the app's org. Blocked when SHARED_GAME_API_URL is not configured. */
     publishAppToShared: PublishAppResult;
     /** Operator only (is_operator). Cuts a new environment release from a cks-game-api git tag: ingests it as available and commits the manifest to the git ref. SIDE EFFECT: makes the version the new redeploy target and writes to GitHub. Use force to overwrite. Writes an audit entry. */
@@ -3028,6 +3075,8 @@ export type Mutation = {
     putCpSecret: CpSecretRow;
     /** Redeploys the environment to a target release version (input.version) or, when omitted, the latest available version for its class, reusing its current flavors/scaling and linked apps. Preserves the environment URLs. No-op-safe: re-running when already at latest still redeploys. If a prior deploy failed but stayed in_progress, it is abandoned first so the redeploy can proceed. Requires the 'manage_environments' org permission. */
     redeployEnvironment: CksEnvironmentChangeOrder;
+    /** Rotate the calling app token for a fresh one (same app, extended TTL) and revoke the old. Call before the current token expires to keep playing without bouncing back through the Overworld. Allowed for app-scoped tokens; re-checks entitlement. */
+    refreshAppToken: AppTokenResponse;
     /** Creates a new (initially unconfirmed) account, sends a confirmation email, and returns an AuthResponse with a session `token` for immediate login (send as `Authorization: Bearer <token>`). Public; throws if the email already exists. */
     register: AuthResponse;
     /** Remove a member from a channel. Requires the 'manage_members' channel permission, except that any member may remove themselves. Notifies Buddy to stop routing to the removed member. Returns true if a membership was removed. */
@@ -3237,6 +3286,9 @@ export type MutationCreateOrgTokenArgs = {
 export type MutationCreateOrganizationArgs = {
     input: CreateOrganizationInput;
 };
+export type MutationCreatePortalAuthorizationCodeArgs = {
+    input: CreatePortalAuthorizationCodeInput;
+};
 export type MutationCreateTeamArgs = {
     input: CreateTeamInput;
 };
@@ -3285,6 +3337,9 @@ export type MutationDeleteUserAppStateArgs = {
 export type MutationDestroyEnvironmentArgs = {
     input: DestroyEnvironmentInput;
 };
+export type MutationExchangePortalCodeArgs = {
+    input: ExchangePortalCodeInput;
+};
 export type MutationForceLogoutUserArgs = {
     userId: Scalars['BigInt']['input'];
 };
@@ -3397,6 +3452,9 @@ export type MutationLinkAppToEnvironmentArgs = {
 export type MutationLoginArgs = {
     loginUserInput: LoginUserInput;
 };
+export type MutationMintAppTokenArgs = {
+    input: MintAppTokenInput;
+};
 export type MutationPublishAppToSharedArgs = {
     appId: Scalars['BigInt']['input'];
     cancelUrl?: InputMaybe<Scalars['String']['input']>;
@@ -3944,6 +4002,16 @@ export type PlayerPulse = {
     /** Number of studios in the percentile comparison pool (studios with all_time_peak > 0). */
     poolSize: Scalars['Int']['output'];
 };
+/** A one-time portal authorization code. Redirect the player to `redirectUri` carrying `code`; the destination game exchanges it (with its PKCE verifier) via exchangePortalCode for an app token. Single-use and short-lived. */
+export type PortalAuthorizationCode = {
+    __typename?: 'PortalAuthorizationCode';
+    /** The one-time authorization code. Deliver it to the destination game origin only (e.g. as a `code` query param on redirectUri). */
+    code: Scalars['String']['output'];
+    /** ISO-8601 UTC expiry of the code (typically ~60s). */
+    expiresAt: Scalars['String']['output'];
+    /** The validated redirect URI the player should be sent to. */
+    redirectUri: Scalars['String']['output'];
+};
 /** Postgres billing tier: bandwidth allotment and capacity charge. Usage metering deferred. */
 export type PostgresBillingTier = {
     __typename?: 'PostgresBillingTier';
@@ -5320,6 +5388,8 @@ export declare enum UdpErrorCode {
     PasswordTooLong = "PASSWORD_TOO_LONG",
     /** Password failed minimum-length validation. */
     PasswordTooShort = "PASSWORD_TOO_SHORT",
+    /** The app-scoped gameplay token has expired. Refresh it (same app, via refreshAppToken) before it lapses, or re-portal through the Overworld for a fresh token, then re-authorize the realtime session. */
+    TokenExpired = "TOKEN_EXPIRED",
     /** The caller lacks the runtime/grid permission required for this action. Grid permissions can load asynchronously, so the first message to a newly entered region may transiently return this — retry shortly. */
     Unauthorized = "UNAUTHORIZED",
     /** Unspecified server error (1). Retry; if it persists, report it. */