@nsxbet/admin-sdk 0.7.0 → 0.8.0

package/CHECKLIST.md

@@ -24,20 +24,28 @@
 - [ ] `src/i18n/locales/pt-BR.json` — Portuguese (Brazil) translations
 - [ ] `src/i18n/locales/es.json` — Spanish translations
 - [ ] `src/i18n/locales/ro.json` — Romanian translations
-- [ ] `.env.staging` — Gateway environment config (staging mode)
+- [ ] `.env` / `.env.development` and/or `.env.staging` — gateway / runtime env (see [Environment Configuration](#environment-configuration))
 
 ## Environment Configuration
 
-- [ ] `.env.staging` exists with `VITE_ADMIN_GATEWAY_URL` configured
-- [ ] `dev` script uses `--mode staging` to load `.env.staging` by default
+- [ ] `ADMIN_GATEWAY_URL` is set in `.env`, `.env.development`, or `.env.staging` (use `.env.staging` when your `dev` script runs with `--mode staging`)
+- [ ] `dev` script uses `--mode staging` to load `.env.staging` by default (non-Lovable flow; Lovable can rely on `adminModule()` defaults — see below)
 
-Expected `.env.staging`:
+### Runtime (`/env.js`)
+
+- [ ] `index.html` includes `<script src="/env.js"></script>` before the app entry (`adminModule()` / `defineModuleConfig()` inject this when gateway injection is enabled)
+- [ ] Shared runtime fields are read via `import { env } from "@nsxbet/admin-sdk"` — not `import.meta.env.VITE_*` for `ADMIN_GATEWAY_URL`, `MOCK_AUTH`, etc.
+
+Expected env snippet (place in `.env`, `.env.development`, or `.env.staging` depending on your setup):
 
 ```bash
 # Gateway URL for BFF token integration (InMemory auth)
 # Fetches real signed JWTs from the admin gateway instead of mock tokens.
 # Staging: https://admin-bff-stg.nsx.dev | Homol: https://admin-bff-homol.nsx.dev | Local: http://localhost:8080
-VITE_ADMIN_GATEWAY_URL=https://admin-bff-stg.nsx.dev
+ADMIN_GATEWAY_URL=https://admin-bff-stg.nsx.dev
+
+# Optional: exposed on window.__ENV__ for app code
+# MOCK_AUTH=true
 ```
 
 ## Module Manifest (`admin.module.json`)
@@ -57,13 +65,32 @@ Expected structure:
 ```json
 {
   "id": "@admin/my-module",
-  "title": { "en-US": "My Module", "pt-BR": "Meu Módulo", "es": "Mi Módulo", "ro": "Modulul Meu" },
+  "title": {
+    "en-US": "My Module",
+    "pt-BR": "Meu Módulo",
+    "es": "Mi Módulo",
+    "ro": "Modulul Meu"
+  },
   "routeBase": "/my-module",
-  "description": { "en-US": "My Module admin module", "pt-BR": "...", "es": "...", "ro": "..." },
+  "description": {
+    "en-US": "My Module admin module",
+    "pt-BR": "...",
+    "es": "...",
+    "ro": "..."
+  },
   "version": "1.0.0",
   "category": "Tools",
   "commands": [
-    { "id": "home", "title": { "en-US": "Home", "pt-BR": "Início", "es": "Inicio", "ro": "Acasă" }, "route": "/my-module/home" }
+    {
+      "id": "home",
+      "title": {
+        "en-US": "Home",
+        "pt-BR": "Início",
+        "es": "Inicio",
+        "ro": "Acasă"
+      },
+      "route": "/my-module/home"
+    }
   ],
   "permissions": {
     "view": ["admin.my-module.view"],
@@ -108,6 +135,7 @@ Expected structure:
 
 - [ ] Uses `defineModuleConfig` from `@nsxbet/admin-sdk/vite` OR spreads `adminModule()` into an existing Vite config
 - [ ] Imports and uses a React plugin (`@vitejs/plugin-react` or `@vitejs/plugin-react-swc`)
+- [ ] `adminModule()` / `defineModuleConfig()` serve `/env.js` in dev/preview (sets `window.__ENV__`) and inject the script tag when gateway injection is enabled; pass `gatewayUrl: null` to disable
 
 Expected (option A — full config):
 
@@ -196,6 +224,7 @@ export default App;
 - [ ] Uses `AdminShell` from `@nsxbet/admin-sdk`
 - [ ] Imports manifest and passes to `modules` prop
 - [ ] Permissions use namespace `admin.<module-name>.*`
+- [ ] Does not pass `bff` on `AdminShell` — standalone module dev uses `createInMemoryAuthClient` and optional gateway JWTs; BFF/Okta cookie auth is for the platform shell in production
 
 Expected (simplified):
 
@@ -204,7 +233,7 @@ import { AdminShell } from "@nsxbet/admin-sdk";
 import manifest from "../admin.module.json";
 import { App } from "./App";
 
-<AdminShell modules={[manifest]} keycloak={config}>
+<AdminShell modules={[manifest]} authClient={authClient}>
   <App />
 </AdminShell>
 ```
@@ -258,13 +287,14 @@ If your module was scaffolded by Lovable, the following differences apply:
 
 ### Environment Configuration (automatic)
 
-`adminModule()` automatically injects `VITE_ADMIN_GATEWAY_URL` with the staging gateway URL (`https://admin-bff-stg.nsx.dev`). No `.env.staging` file or `--mode staging` script is needed for Lovable projects.
+`adminModule()` serves `/env.js` in dev/preview so `window.__ENV__` includes `ADMIN_GATEWAY_URL` (default staging gateway `https://admin-bff-stg.nsx.dev`). No `.env.staging` file or `--mode staging` script is needed for Lovable projects.
 
 - [ ] Do NOT create `.env.staging` — the Vite plugin handles it
 - [ ] Do NOT add `--mode staging` to the dev script
 
 To override the gateway URL, either:
-- Set `VITE_ADMIN_GATEWAY_URL` in a `.env` or `.env.local` file
+
+- Set `ADMIN_GATEWAY_URL` in a `.env` or `.env.local` file
 - Pass `gatewayUrl` option: `...adminModule({ gatewayUrl: "http://localhost:8080" })`
 - Disable injection: `...adminModule({ gatewayUrl: null })`
 
@@ -314,7 +344,11 @@ import "./index.css";
 const moduleManifest = manifest as AdminModuleManifest;
 
 const mockUsers = createMockUsersFromRoles({
-  admin: ["admin.mymodule.view", "admin.mymodule.edit", "admin.mymodule.delete"],
+  admin: [
+    "admin.mymodule.view",
+    "admin.mymodule.edit",
+    "admin.mymodule.delete",
+  ],
   editor: ["admin.mymodule.view", "admin.mymodule.edit"],
   viewer: ["admin.mymodule.view"],
   noAccess: [],
@@ -327,7 +361,7 @@ ReactDOM.createRoot(document.getElementById("root")!).render(
     <AdminShell modules={[moduleManifest]} authClient={authClient}>
       <App />
     </AdminShell>
-  </React.StrictMode>
+  </React.StrictMode>,
 );
 ```
 
@@ -341,3 +375,4 @@ ReactDOM.createRoot(document.getElementById("root")!).render(
 - [ ] No raw `fetch()` or `window.fetch()` calls — use `useFetch()` from the SDK
 - [ ] No direct date formatting (`toLocaleDateString`, `toLocaleTimeString`, `Intl.DateTimeFormat`, dayjs/moment `.format()`, date-fns `format`) — use `<Timestamp />` or `useTimestamp()` from the SDK
 - [ ] Do NOT scaffold shadcn/ui components locally — use `@nsxbet/admin-ui` which ships them pre-configured
+- [ ] No `import.meta.env.VITE_*` for runtime gateway/auth settings (`ADMIN_GATEWAY_URL`, `MOCK_AUTH`, etc.) — use `/env.js` and `import { env } from "@nsxbet/admin-sdk"`

package/README.md

@@ -192,10 +192,6 @@ initI18n();
 
 const moduleManifest = manifest as AdminModuleManifest;
 
-// Check environment variable to toggle between mock auth and Keycloak
-const useKeycloak = import.meta.env.VITE_MOCK_AUTH === "false";
-
-// Create mock users with module-specific permissions
 const mockUsers = createMockUsersFromRoles({
   admin: ["admin.mymodule.view", "admin.mymodule.edit", "admin.mymodule.delete"],
   editor: ["admin.mymodule.view", "admin.mymodule.edit"],
@@ -203,25 +199,13 @@ const mockUsers = createMockUsersFromRoles({
   noAccess: [],
 });
 
-// Use in-memory auth by default (shows user selector), or Keycloak if configured
-const authClient = useKeycloak
-  ? undefined
-  : createInMemoryAuthClient({ users: mockUsers });
+const authClient = createInMemoryAuthClient({ users: mockUsers });
 
 ReactDOM.createRoot(document.getElementById("root")!).render(
   <React.StrictMode>
     <AdminShell
       modules={[moduleManifest]}
       authClient={authClient}
-      keycloak={
-        useKeycloak
-          ? {
-              url: "http://localhost:8080",
-              realm: "admin",
-              clientId: "admin-shell",
-            }
-          : undefined
-      }
     >
       <App />
     </AdminShell>
@@ -229,6 +213,8 @@ ReactDOM.createRoot(document.getElementById("root")!).render(
 );
 ```
 
+**Module standalone dev** uses the in-memory client and **UserSelector**, which fetches JWTs via **`GET {gateway}/auth/token`**. Do not pass **`bff`** here — BFF / Okta cookie auth is for the **platform shell** in production, not for local module dev servers.
+
 ### File: `src/App.tsx`
 
 ```tsx
@@ -468,7 +454,6 @@ TypeScript declarations for environment variables and platform API:
 
 declare global {
   interface ImportMetaEnv {
-    readonly VITE_MOCK_AUTH?: string;
     readonly VITE_ALLOWED_MODULE_ORIGINS?: string;
   }
 
@@ -480,9 +465,6 @@ declare global {
     __ADMIN_PLATFORM_API__?: import("@nsxbet/admin-sdk").PlatformAPI;
     __ENV__?: {
       ENVIRONMENT: string;
-      KEYCLOAK_URL: string;
-      KEYCLOAK_REALM: string;
-      KEYCLOAK_CLIENT_ID: string;
     };
   }
 }
@@ -514,10 +496,7 @@ Environment configuration for development:
 
 ```bash
 # Use mock authentication with user selector (default: true)
-VITE_MOCK_AUTH=true
-
-# Set to "false" to use Keycloak authentication
-# VITE_MOCK_AUTH=false
+MOCK_AUTH=true
 
 # Module URL allowlist (shell mode only). Comma-separated patterns.
 # Supports *.domain wildcard (e.g. *.nsx.dev matches modules.nsx.dev, nsx.dev).
@@ -621,7 +600,7 @@ export default defineModuleConfig({
 });
 ```
 
-> **Important:** Each module must use a unique port. The default is `8080` (matching Lovable's default). Modules running alongside Keycloak (which also uses port 8080) should specify an explicit port. Standard assignments:
+> **Important:** Each module must use a unique port. The default is `8080` (matching Lovable's default). Standard assignments:
 > - Shell: 3000
 > - API: 4000
 > - Modules: 3002, 3003, 3004, etc.
@@ -680,7 +659,7 @@ export default defineConfig(({ mode }) => ({
 
 ### Automatic Environment Injection
 
-`adminModule()` includes an env injection plugin that automatically sets `VITE_ADMIN_GATEWAY_URL` at build time. This ensures Lovable projects get real JWT tokens from the staging gateway without any manual `.env` configuration.
+`adminModule()` includes a plugin that serves `/env.js` in dev/preview and injects `<script src="/env.js">` into `index.html`. The script sets `window.__ENV__` (including `ADMIN_GATEWAY_URL` from your `.env` or a default staging URL). The SDK reads this via `import { env } from "@nsxbet/admin-sdk"`.
 
 **Precedence order** (highest to lowest):
 
@@ -815,7 +794,7 @@ function MyComponent() {
 
 | Method | Returns | Description |
 |--------|---------|-------------|
-| `hasPermission(perm)` | boolean | Check if user has permission. Returns `false` during Keycloak initialization until auth completes. |
+| `hasPermission(perm)` | boolean | Check if user has permission. Returns `false` during auth initialization until auth completes. |
 | `getUser()` | User | Get current user info |
 | `getAccessToken()` | Promise\<string\> | Get JWT token |
 | `logout()` | void | Log out user |
@@ -1015,8 +994,8 @@ The polling interval is resolved from `REGISTRY_POLL_INTERVAL` (milliseconds):
 
 | Source | Example |
 |--------|---------|
-| `window.__ENV__.REGISTRY_POLL_INTERVAL` | Docker runtime injection |
-| `import.meta.env.VITE_REGISTRY_POLL_INTERVAL` | Vite env var |
+| Explicit `registryPollInterval` prop on `AdminShell` | Shell passes from env config |
+| `window.__ENV__.REGISTRY_POLL_INTERVAL` | Fallback for non-shell consumers |
 | Environment default | `local`: 60s, `staging`: 5min, `production`: 15min |
 
 Set `REGISTRY_POLL_INTERVAL=0` to disable polling entirely.
@@ -1114,12 +1093,12 @@ const authClient = createInMemoryAuthClient({ users: customUsers });
 |--------|------|---------|-------------|
 | `users` | MockUser[] | **required** | Mock users available for selection |
 | `storageKey` | string | `"@nsxbet/auth"` | localStorage key for persistence |
-| `gatewayUrl` | string \| null | `VITE_ADMIN_GATEWAY_URL` env var | Admin gateway URL for real JWT tokens |
+| `gatewayUrl` | string \| null | `null` | Admin gateway URL for real JWT tokens |
 | `tokenTimeout` | number | `5000` | Timeout in ms for gateway token fetch |
 
 ### Gateway Token Integration (BFF)
 
-When `VITE_ADMIN_GATEWAY_URL` is set (or `gatewayUrl` is passed explicitly), the InMemory auth client fetches real signed JWTs from the admin gateway instead of returning mock token strings. This enables end-to-end testing against backends that validate tokens.
+When `gatewayUrl` is passed explicitly, the InMemory auth client fetches real signed JWTs from the admin gateway instead of returning mock token strings. This enables end-to-end testing against backends that validate tokens.
 
 **How it works:**
 
@@ -1131,11 +1110,10 @@ When `VITE_ADMIN_GATEWAY_URL` is set (or `gatewayUrl` is passed explicitly), the
 
 **Gateway URL resolution order:**
 
-1. Explicit `gatewayUrl` option passed to `createInMemoryAuthClient()`
-2. `import.meta.env.VITE_ADMIN_GATEWAY_URL` environment variable
-3. If neither is set, BFF integration is disabled (mock tokens, current behavior)
+1. Explicit `gatewayUrl` option passed to `createInMemoryAuthClient()` (or `null` to disable gateway tokens)
+2. Otherwise `env.adminGatewayUrl` from `window.__ENV__` (set by `/env.js` from the shell or the `adminModule()` dev server)
 
-> **Vite plugin auto-injection:** When using `adminModule()` or `defineModuleConfig()` from `@nsxbet/admin-sdk/vite`, the `VITE_ADMIN_GATEWAY_URL` environment variable is automatically set to the staging gateway URL. No `.env.staging` file or `--mode staging` script is needed. See the [Vite Configuration](#vite-configuration) section for override options.
+> **Vite plugin:** When using `adminModule()` or `defineModuleConfig()`, `/env.js` is served in dev and lists `ADMIN_GATEWAY_URL` from your `.env` or the default staging gateway. See the [Vite Configuration](#vite-configuration) section for override options (`gatewayUrl: null` disables `/env.js` entirely).
 
 **Error handling:**
 
@@ -1146,7 +1124,7 @@ The UserSelector shows loading, error, and timeout states during the token fetch
 
 ```bash
 # Add to your .env file to enable gateway token integration
-VITE_ADMIN_GATEWAY_URL=https://admin-bff-stg.nsx.dev
+ADMIN_GATEWAY_URL=https://admin-bff-stg.nsx.dev
 ```
 
 ## Module URL Allowlist (Shell Mode)
@@ -1159,53 +1137,25 @@ When the shell loads modules dynamically from URLs, it validates each URL agains
 
 **Production:** Set `VITE_ALLOWED_MODULE_ORIGINS` in your build environment. If unset or empty, all module loads fail with a clear error.
 
-## Keycloak Configuration (Production Auth)
+## BFF / Okta cookie auth (recommended)
 
-For production or when testing with real authentication, configure Keycloak:
+Production auth should go through **admin-bff**: the BFF sets an HttpOnly `access_token` cookie and exposes **`GET /me`** for identity. The shell does not read the JWT in the browser.
 
-### Prerequisites
-
-1. Keycloak server running (default: `http://localhost:8080`)
-2. Realm named `admin` created
-3. Client named `admin-shell` configured with:
-   - Client Protocol: `openid-connect`
-   - Access Type: `public`
-   - Valid Redirect URIs: `http://localhost:3003/*`
-
-### Enable Keycloak in Development
-
-Set the environment variable in `.env.local`:
-
-```bash
-VITE_MOCK_AUTH=false
-```
-
-Or pass the `keycloak` prop directly without `authClient`:
+### AdminShell
 
 ```tsx
 <AdminShell
   modules={[manifest]}
-  keycloak={{
-    url: "http://localhost:8080",
-    realm: "admin",
-    clientId: "admin-shell",
-  }}
->
-  <App />
-</AdminShell>
+  bff
+  // or: bff={{ baseUrl: "https://admin.example.com" }}
+/>
 ```
 
-### Mock Auth Production Guard
-
-In production builds, AdminShell requires authentication configuration. If you omit both `authClient` and `keycloak` props, the shell throws an error unless you explicitly set `VITE_MOCK_AUTH=true`. When mock auth is used in production with `VITE_MOCK_AUTH=true`, a console warning is logged. Always use Keycloak (or another real auth client) for production deployments.
+Use the same origin as the BFF (or a dev proxy) so `credentials: 'include'` sends the cookie. **`getAccessToken()`** returns **`null`** for this client — use **`useFetch`** / **`api.fetch`**, which send credentialed requests when the token is null.
 
-### Keycloak Configuration Options
+### Production Guard
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `url` | string | Keycloak server URL |
-| `realm` | string | Realm name |
-| `clientId` | string | Client ID |
+In production deployments, configure **`bff`** (admin-bff) for real authentication. If neither `authClient` nor `bff` is provided, AdminShell uses in-memory mock authentication.
 
 ## DO NOT (Common Mistakes)
 

package/dist/auth/client/bff.d.ts

@@ -0,0 +1,38 @@
+/**
+ * BFF / Okta cookie auth client (admin-bff)
+ *
+ * After the Okta OAuth flow, the BFF redirects back with `token`, `expires`,
+ * and `token_type` as query params. The client extracts these, decodes the JWT
+ * to build the user, and persists the token in localStorage. Falls back to
+ * `GET /me` (cookie-based) when no token is present.
+ */
+import type { AuthClient } from './interface';
+export interface BffAuthClientOptions {
+    /** Base URL of admin-bff (no trailing slash). Defaults to `window.location.origin`. */
+    bffBaseUrl?: string;
+}
+/** admin-bff `GET /me` JSON (subset). */
+export interface BffMeResponse {
+    subject: string;
+    email: string;
+    groups?: string[];
+    roles?: string[];
+    scopes?: string[];
+}
+export interface BffAuthClient extends AuthClient {
+    readonly type: 'bff';
+    readonly bffBaseUrl: string;
+}
+/** Mark that the user explicitly logged out — skips `/me` auto-login until cleared (e.g. by LoginPage). */
+export declare function setLoggedOutFlag(): void;
+export declare function clearLoggedOutFlag(): void;
+export declare function isLoggedOutFlag(): boolean;
+/**
+ * Create an auth client that uses the admin-bff Okta flow.
+ *
+ * Auth flow: BFF redirects back with `?token=<JWT>&expires=...&token_type=Bearer`.
+ * The JWT is decoded client-side for user identity. `getAccessToken()` returns the
+ * JWT for bearer auth on API calls. Falls back to `GET /me` (cookie-based) when
+ * running behind the same origin as the BFF.
+ */
+export declare function createBffAuthClient(options?: BffAuthClientOptions): BffAuthClient;

package/dist/auth/client/bff.js

@@ -0,0 +1,270 @@
+/**
+ * BFF / Okta cookie auth client (admin-bff)
+ *
+ * After the Okta OAuth flow, the BFF redirects back with `token`, `expires`,
+ * and `token_type` as query params. The client extracts these, decodes the JWT
+ * to build the user, and persists the token in localStorage. Falls back to
+ * `GET /me` (cookie-based) when no token is present.
+ */
+const TOKEN_STORAGE_KEY = 'admin-bff-token';
+const EXPIRES_STORAGE_KEY = 'admin-bff-token-expires';
+const LOGGED_OUT_FLAG_KEY = 'admin-bff-logged-out';
+/** Mark that the user explicitly logged out — skips `/me` auto-login until cleared (e.g. by LoginPage). */
+export function setLoggedOutFlag() {
+    try {
+        localStorage.setItem(LOGGED_OUT_FLAG_KEY, '1');
+    }
+    catch {
+        /* private browsing */
+    }
+}
+export function clearLoggedOutFlag() {
+    try {
+        localStorage.removeItem(LOGGED_OUT_FLAG_KEY);
+    }
+    catch {
+        /* ok */
+    }
+}
+export function isLoggedOutFlag() {
+    try {
+        return localStorage.getItem(LOGGED_OUT_FLAG_KEY) === '1';
+    }
+    catch {
+        return false;
+    }
+}
+function normalizeBaseUrl(url) {
+    return url.replace(/\/+$/, '');
+}
+function resolveDefaultBffBaseUrl() {
+    if (typeof window !== 'undefined' && window.location?.origin) {
+        return normalizeBaseUrl(window.location.origin);
+    }
+    return 'http://localhost:3000';
+}
+function meToUser(me) {
+    const roles = [...(me.groups ?? []), ...(me.roles ?? [])];
+    return {
+        id: me.subject,
+        email: me.email ?? '',
+        displayName: me.email || me.subject,
+        roles,
+    };
+}
+/** Decode a JWT payload without signature verification (the BFF already verified it). */
+function decodeJwtPayload(token) {
+    const parts = token.split('.');
+    if (parts.length !== 3)
+        throw new Error('Invalid JWT format');
+    const base64 = parts[1].replace(/-/g, '+').replace(/_/g, '/');
+    return JSON.parse(atob(base64));
+}
+function jwtToUser(payload) {
+    const groups = payload.groups ?? [];
+    const roles = payload.roles ?? [];
+    return {
+        id: payload.sub ?? '',
+        email: payload.email ?? '',
+        displayName: payload.email || payload.sub || '',
+        roles: [...groups, ...roles],
+    };
+}
+function matchesPermission(userRoles, permission) {
+    if (userRoles.includes('*'))
+        return true;
+    return userRoles.some((role) => {
+        if (role === permission)
+            return true;
+        if (role.endsWith('.*')) {
+            const prefix = role.slice(0, -2);
+            return permission.startsWith(prefix);
+        }
+        return false;
+    });
+}
+/** Read token + expires from URL query params, then clean the URL. */
+function consumeTokenFromUrl() {
+    if (typeof window === 'undefined')
+        return null;
+    const params = new URLSearchParams(window.location.search);
+    const token = params.get('token');
+    const expires = params.get('expires');
+    if (!token)
+        return null;
+    params.delete('token');
+    params.delete('expires');
+    params.delete('token_type');
+    const cleanSearch = params.toString();
+    const cleanUrl = window.location.pathname + (cleanSearch ? `?${cleanSearch}` : '') + window.location.hash;
+    window.history.replaceState(null, '', cleanUrl);
+    return { token, expires: expires ?? '' };
+}
+function storeToken(token, expires) {
+    try {
+        localStorage.setItem(TOKEN_STORAGE_KEY, token);
+        localStorage.setItem(EXPIRES_STORAGE_KEY, expires);
+    }
+    catch { /* private browsing */ }
+}
+function loadStoredToken() {
+    try {
+        const token = localStorage.getItem(TOKEN_STORAGE_KEY);
+        const expires = localStorage.getItem(EXPIRES_STORAGE_KEY);
+        if (!token)
+            return null;
+        return { token, expires: expires ?? '' };
+    }
+    catch {
+        return null;
+    }
+}
+function clearStoredToken() {
+    try {
+        localStorage.removeItem(TOKEN_STORAGE_KEY);
+        localStorage.removeItem(EXPIRES_STORAGE_KEY);
+    }
+    catch { /* ok */ }
+}
+function isTokenExpired(expires) {
+    if (!expires)
+        return false;
+    try {
+        return new Date(decodeURIComponent(expires)).getTime() <= Date.now();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Create an auth client that uses the admin-bff Okta flow.
+ *
+ * Auth flow: BFF redirects back with `?token=<JWT>&expires=...&token_type=Bearer`.
+ * The JWT is decoded client-side for user identity. `getAccessToken()` returns the
+ * JWT for bearer auth on API calls. Falls back to `GET /me` (cookie-based) when
+ * running behind the same origin as the BFF.
+ */
+export function createBffAuthClient(options = {}) {
+    const bffBaseUrl = normalizeBaseUrl(options.bffBaseUrl ?? resolveDefaultBffBaseUrl());
+    let currentUser = null;
+    let accessToken = null;
+    let initialized = false;
+    const subscribers = new Set();
+    function notifySubscribers() {
+        const state = {
+            isAuthenticated: currentUser !== null,
+            user: currentUser,
+        };
+        subscribers.forEach((cb) => cb(state));
+    }
+    async function fetchMe() {
+        const res = await fetch(`${bffBaseUrl}/me`, {
+            credentials: 'include',
+        });
+        if (res.status === 401) {
+            return { ok: false };
+        }
+        if (!res.ok) {
+            throw new Error(`BFF /me failed: ${res.status}`);
+        }
+        const data = (await res.json());
+        if (!data?.subject) {
+            throw new Error('BFF /me: missing subject');
+        }
+        return { ok: true, user: meToUser(data) };
+    }
+    function authenticateWithToken(token, expires) {
+        try {
+            if (isTokenExpired(expires)) {
+                clearStoredToken();
+                return false;
+            }
+            const payload = decodeJwtPayload(token);
+            currentUser = jwtToUser(payload);
+            accessToken = token;
+            storeToken(token, expires);
+            return true;
+        }
+        catch (e) {
+            console.warn('[BffAuthClient] Failed to decode token from redirect:', e);
+            clearStoredToken();
+            return false;
+        }
+    }
+    const client = {
+        type: 'bff',
+        bffBaseUrl,
+        async initialize() {
+            // 1. Check URL for token from BFF redirect (highest priority)
+            const fromUrl = consumeTokenFromUrl();
+            if (fromUrl && authenticateWithToken(fromUrl.token, fromUrl.expires)) {
+                initialized = true;
+                notifySubscribers();
+                return true;
+            }
+            // 2. Check localStorage for a previously stored token
+            const stored = loadStoredToken();
+            if (stored && authenticateWithToken(stored.token, stored.expires)) {
+                initialized = true;
+                notifySubscribers();
+                return true;
+            }
+            if (isLoggedOutFlag()) {
+                initialized = true;
+                currentUser = null;
+                accessToken = null;
+                notifySubscribers();
+                return false;
+            }
+            // 3. Fall back to /me (same-origin / cookie mode)
+            try {
+                const result = await fetchMe();
+                initialized = true;
+                if (result.ok) {
+                    currentUser = result.user;
+                    notifySubscribers();
+                    return true;
+                }
+                currentUser = null;
+                notifySubscribers();
+                return false;
+            }
+            catch (e) {
+                console.warn('[BffAuthClient] /me failed; redirecting flow will send user to login:', e);
+                initialized = true;
+                currentUser = null;
+                notifySubscribers();
+                return false;
+            }
+        },
+        isAuthenticated() {
+            return currentUser !== null;
+        },
+        getUser() {
+            return currentUser;
+        },
+        async getAccessToken() {
+            return accessToken;
+        },
+        hasPermission(permission) {
+            if (!initialized || !currentUser) {
+                return false;
+            }
+            return matchesPermission(currentUser.roles, permission);
+        },
+        logout() {
+            currentUser = null;
+            accessToken = null;
+            clearStoredToken();
+            setLoggedOutFlag();
+            notifySubscribers();
+        },
+        subscribe(callback) {
+            subscribers.add(callback);
+            return () => {
+                subscribers.delete(callback);
+            };
+        },
+    };
+    return client;
+}

package/dist/auth/client/in-memory.d.ts

@@ -46,7 +46,7 @@ export interface InMemoryAuthClientOptions {
     users: MockUser[];
     /** localStorage key prefix (defaults to '@nsxbet/auth') */
     storageKey?: string;
-    /** Admin gateway URL for fetching real signed JWTs. If not set, falls back to import.meta.env.VITE_ADMIN_GATEWAY_URL. If neither is set, BFF integration is disabled. */
+    /** Override gateway URL for fetching real signed JWTs. Defaults to `env.adminGatewayUrl` from `/env.js`. Pass `null` to disable. */
     gatewayUrl?: string | null;
     /** Timeout in milliseconds for gateway token fetch requests (defaults to 5000) */
     tokenTimeout?: number;