@frontera-sdk/core 1.43.9 → 1.44.0

package/README.md

@@ -8,23 +8,28 @@ bun add @frontera-sdk/core react react-dom @tanstack/react-query
 ```
 
 ```tsx
-import { createFronteraApp } from '@frontera-sdk/core/create-frontera-app'
+import { FronteraAppProvider } from '@frontera-sdk/core/react'
 
-import App from './App'
-
-createFronteraApp(<App />)
+export function Providers({ children }: { children: React.ReactNode }) {
+  return <FronteraAppProvider>{children}</FronteraAppProvider>
+}
 ```
 
-`createFronteraApp` completes the handshake, adopts the host's palette,
-installs the error boundary that reports crashes back to the platform, and only
-then mounts. An app has no data scope until the host says who it is — which is
-why opening the app's own origin directly renders a refusal panel rather than
-the app.
+`FronteraAppProvider` selects one configured transport before connecting:
+embedded postMessage bridge, same-origin standalone session, or loopback local
+session broker. All three synthesize the same `BridgeInit`, so Blueprint and
+other domain providers do not need transport-specific branches. A missing
+transport renders a configuration diagnostic immediately.
+
+`createFronteraApp()` remains the Vite compatibility wrapper. Embedded
+`navigate()` synchronizes the platform-owned URL; standalone and local Apps
+own routing themselves.
 
 ## Entry points
 
 | Import | What it is |
 |---|---|
+| `@frontera-sdk/core/react` | `FronteraAppProvider`, `useFronteraApp`, and mode types |
 | `@frontera-sdk/core/create-frontera-app` | app bootstrap and `useFronteraApp` |
 | `@frontera-sdk/core/client` | the typed platform client |
 | `@frontera-sdk/core/config` | credential and origin resolution |
@@ -34,6 +39,9 @@ the app.
 | `@frontera-sdk/core/theme` | applying the host's design tokens |
 | `@frontera-sdk/core/errors` | the error taxonomy, `code` mirroring the service |
 
+Standalone and local sessions refresh their short-lived App token at 80% of
+its lifetime. The browser never receives a long-lived workspace key.
+
 Published as TypeScript source. Every consumer is a bundler or `tsc`, so a
 build step would emit output the consumer immediately re-transpiles.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/core",
-  "version": "1.43.9",
+  "version": "1.44.0",
   "description": "Frontera app runtime: the platform bridge client, app bootstrap and typed platform client.",
   "keywords": [
     "frontera",
@@ -56,6 +56,10 @@
     "./create-frontera-app": {
       "types": "./src/create-frontera-app.tsx",
       "import": "./src/create-frontera-app.tsx"
+    },
+    "./react": {
+      "types": "./src/react.ts",
+      "import": "./src/react.ts"
     }
   },
   "scripts": {

package/src/app-session.ts

@@ -0,0 +1,108 @@
+import type { BridgeSession } from './bridge-client'
+import { isHostMessage, type BridgeInit } from './bridge-protocol'
+import type { FronteraRuntimeGlobal } from './config'
+
+export type FronteraAppMode = 'embedded' | 'standalone' | 'local'
+
+export function detectAppMode(
+  runtime: FronteraRuntimeGlobal,
+  framed: boolean,
+): FronteraAppMode | null {
+  if (framed && runtime.platformOrigin) return 'embedded'
+  if (runtime.sessionEndpoint) return 'standalone'
+  if (runtime.devSessionEndpoint) return 'local'
+  return null
+}
+
+interface SessionResponse {
+  init: BridgeInit
+  expiresAt: number
+}
+
+export interface EndpointSessionOptions {
+  fetchImpl?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>
+  now?: () => number
+  setTimer?: (callback: () => void, delay: number) => unknown
+  clearTimer?: (timer: unknown) => void
+}
+
+function parseExpiry(value: unknown): number {
+  const parsed = typeof value === 'number' ? value : typeof value === 'string' ? Date.parse(value) : Number.NaN
+  if (!Number.isFinite(parsed)) throw new Error('Frontera session response has an invalid expiresAt')
+  return parsed
+}
+
+function parseSessionResponse(value: unknown): SessionResponse {
+  const envelope = value as { data?: unknown } | null
+  const raw = (envelope && typeof envelope === 'object' && 'data' in envelope ? envelope.data : value) as
+    | Record<string, unknown>
+    | null
+  if (!raw || typeof raw !== 'object' || !isHostMessage(raw.init) || raw.init.type !== 'frontera:init') {
+    throw new Error('Frontera session response is malformed')
+  }
+  return { init: raw.init, expiresAt: parseExpiry(raw.expiresAt) }
+}
+
+async function fetchSession(
+  endpoint: string,
+  fetchImpl: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>,
+): Promise<SessionResponse> {
+  const response = await fetchImpl(endpoint, {
+    credentials: 'include',
+    headers: { accept: 'application/json' },
+  })
+  if (!response.ok) throw new Error(`Frontera session request failed with ${response.status}`)
+  return parseSessionResponse(await response.json())
+}
+
+/** Build a bridge-compatible session from standalone or local HTTP auth. */
+export async function connectToSessionEndpoint(
+  endpoint: string,
+  options: EndpointSessionOptions = {},
+): Promise<BridgeSession> {
+  const fetchImpl = options.fetchImpl ?? fetch
+  const now = options.now ?? Date.now
+  const setTimer = options.setTimer ?? ((callback, delay) => setTimeout(callback, delay))
+  const clearTimer = options.clearTimer ?? ((handle) => clearTimeout(handle as ReturnType<typeof setTimeout>))
+  const first = await fetchSession(endpoint, fetchImpl)
+  const tokenHandlers = new Set<(token: string) => void>()
+  let disposed = false
+  let timer: unknown
+
+  const schedule = (expiresAt: number) => {
+    if (disposed) return
+    const delay = Math.max(0, Math.floor((expiresAt - now()) * 0.8))
+    timer = setTimer(() => {
+      void fetchSession(endpoint, fetchImpl)
+        .then((next) => {
+          if (disposed) return
+          for (const handler of tokenHandlers) handler(next.init.token)
+          schedule(next.expiresAt)
+        })
+        // A revoked session must not keep emitting credentials. Requests made
+        // with the previous short-lived token naturally stop at its expiry.
+        .catch(() => {})
+    }, delay)
+  }
+  schedule(first.expiresAt)
+
+  return {
+    init: first.init,
+    send() {},
+    onState() {
+      return () => {}
+    },
+    onToken(handler) {
+      tokenHandlers.add(handler)
+      return () => tokenHandlers.delete(handler)
+    },
+    onTheme() {
+      return () => {}
+    },
+    dispose() {
+      disposed = true
+      if (timer !== undefined) clearTimer(timer)
+      tokenHandlers.clear()
+    },
+  }
+}

package/src/config.ts

@@ -36,6 +36,10 @@ export interface FronteraRuntimeGlobal {
   appId?: string
   version?: string
   platformOrigin?: string
+  /** Same-origin short-lived user session for direct App visits. */
+  sessionEndpoint?: string
+  /** Loopback-only CLI broker used during authenticated local development. */
+  devSessionEndpoint?: string
 }
 
 export function readRuntimeGlobal(): FronteraRuntimeGlobal {

package/src/create-frontera-app.tsx

@@ -14,6 +14,12 @@ import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
 import { connectToHost, type BridgeSession } from './bridge-client'
 import type { BridgeInit } from './bridge-protocol'
 import { FronteraClient } from './client'
+import { readRuntimeGlobal } from './config'
+import {
+  connectToSessionEndpoint,
+  detectAppMode,
+  type FronteraAppMode,
+} from './app-session'
 import { applyHostTheme } from './theme'
 
 /**
@@ -32,6 +38,7 @@ import { applyHostTheme } from './theme'
  */
 
 export interface FronteraAppValue {
+  mode: FronteraAppMode
   /** Everything the host said at handshake, including `path`. */
   init: BridgeInit
   client: FronteraClient
@@ -73,6 +80,7 @@ export interface CreateFronteraAppOptions {
 
 interface BoundaryProps {
   onError: (error: Error, info: ErrorInfo) => void
+  fallback?: (error: Error) => ReactNode
   children: ReactNode
 }
 
@@ -96,7 +104,7 @@ class AppErrorBoundary extends Component<BoundaryProps, { error: Error | null }>
 
   render() {
     if (!this.state.error) return this.props.children
-    return diagnostic('This app stopped rendering', this.state.error.message)
+    return this.props.fallback?.(this.state.error) ?? diagnostic('This app stopped rendering', this.state.error.message)
   }
 }
 
@@ -126,12 +134,16 @@ function diagnostic(title: string, detail: string): ReactNode {
  */
 function FronteraRoot({
   session,
-  app,
+  mode,
+  children,
   providers,
+  errorFallback,
 }: {
   session: BridgeSession
-  app: ReactNode
+  mode: FronteraAppMode
+  children: ReactNode
   providers: FronteraProvider[]
+  errorFallback?: (error: Error) => ReactNode
 }) {
   const { init } = session
   const [client, setClient] = useState(
@@ -140,24 +152,27 @@ function FronteraRoot({
         apiBaseUrl: init.apiBaseUrl,
         orgId: init.orgId ?? undefined,
         workspaceId: init.workspaceId ?? undefined,
-        credential: { kind: 'apiKey', key: init.token },
+        credential: { kind: 'token', token: init.token },
       }),
   )
 
   useEffect(
-    () => session.onToken((token) => setClient((c) => c.withCredential({ kind: 'apiKey', key: token }))),
+    () => session.onToken((token) => setClient((c) => c.withCredential({ kind: 'token', token }))),
     [session],
   )
 
   useEffect(() => session.onTheme((theme) => applyHostTheme(theme)), [session])
 
   const value: FronteraAppValue = {
+    mode,
     init,
     client,
-    navigate: (path) => session.send({ type: 'frontera:navigate', path }),
+    navigate: (path) => {
+      if (mode === 'embedded') session.send({ type: 'frontera:navigate', path })
+    },
   }
 
-  let tree: ReactNode = app
+  let tree: ReactNode = children
   // Applied in reverse so the FIRST provider listed ends up outermost, which is
   // the order a reader expects from the array.
   for (const provider of [...providers].reverse()) tree = provider(value, tree)
@@ -165,6 +180,7 @@ function FronteraRoot({
   return (
     <FronteraAppReactContext.Provider value={value}>
       <AppErrorBoundary
+        fallback={errorFallback}
         onError={(error) =>
           session.send({ type: 'frontera:error', message: error.message, stack: error.stack })
         }
@@ -175,6 +191,100 @@ function FronteraRoot({
   )
 }
 
+export interface FronteraAppProviderProps {
+  children: ReactNode
+  providers?: FronteraProvider[]
+  loading?: ReactNode
+  errorFallback?: (error: Error) => ReactNode
+  /** Compatibility hooks used by createFronteraApp. */
+  queryClient?: QueryClient
+  timeoutMs?: number
+}
+
+/**
+ * Transport-neutral React entry point for embedded, standalone, and local Apps.
+ * Mode selection happens before connection, so an ordinary standalone page
+ * never waits for an iframe handshake that cannot succeed.
+ */
+export function FronteraAppProvider({
+  children,
+  providers = [],
+  loading = diagnostic('Connecting to Frontera', 'Establishing an authenticated App session.'),
+  errorFallback,
+  queryClient: providedQueryClient,
+  timeoutMs,
+}: FronteraAppProviderProps): ReactNode {
+  const [connection, setConnection] = useState<{
+    mode: FronteraAppMode
+    session: BridgeSession
+  } | null>(null)
+  const [error, setError] = useState<Error | null>(null)
+  const [queryClient] = useState(
+    () =>
+      providedQueryClient ??
+      new QueryClient({
+        defaultOptions: { queries: { refetchOnWindowFocus: false, retry: 1 } },
+      }),
+  )
+
+  useEffect(() => {
+    const runtime = readRuntimeGlobal()
+    const framed = typeof window !== 'undefined' && window.parent !== window
+    const mode = detectAppMode(runtime, framed)
+    if (!mode) {
+      setError(
+        new Error(
+          'Frontera App is not configured: no embedded host, standalone session endpoint, or local development session endpoint was provided.',
+        ),
+      )
+      return
+    }
+
+    let active = true
+    let sessionToDispose: BridgeSession | null = null
+    const connected =
+      mode === 'embedded'
+        ? connectToHost({ parentOrigin: runtime.platformOrigin, timeoutMs })
+        : connectToSessionEndpoint(
+            mode === 'standalone' ? runtime.sessionEndpoint! : runtime.devSessionEndpoint!,
+          )
+    void connected
+      .then((session) => {
+        sessionToDispose = session
+        if (!active) {
+          session.dispose()
+          return
+        }
+        applyHostTheme(session.init.theme)
+        setConnection({ mode, session })
+      })
+      .catch((reason) => {
+        if (active) setError(reason instanceof Error ? reason : new Error(String(reason)))
+      })
+
+    return () => {
+      active = false
+      sessionToDispose?.dispose()
+    }
+  }, [])
+
+  if (error) return errorFallback?.(error) ?? diagnostic('Frontera App could not start', error.message)
+  if (!connection) return loading
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      <FronteraRoot
+        mode={connection.mode}
+        session={connection.session}
+        providers={providers}
+        errorFallback={errorFallback}
+      >
+        {children}
+      </FronteraRoot>
+    </QueryClientProvider>
+  )
+}
+
 export async function createFronteraApp(
   app: ReactNode,
   options: CreateFronteraAppOptions = {},
@@ -187,34 +297,15 @@ export async function createFronteraApp(
 
   const root = createRoot(element)
 
-  let session: BridgeSession
-  try {
-    session = await connectToHost({ timeoutMs: options.timeoutMs })
-  } catch (err) {
-    // NOT a thrown rejection. This is the everyday outcome of running `vite`
-    // directly, and an unhandled rejection in the console reads as a crash in
-    // the app's own code. A visible panel says what actually happened.
-    const detail = err instanceof Error ? err.message : String(err)
-    root.render(diagnostic('This app runs inside Frontera', detail))
-    return
-  }
-
-  // Before the first paint, so the app never renders in the wrong palette.
-  applyHostTheme(session.init.theme)
-
-  const queryClient =
-    options.queryClient ??
-    new QueryClient({
-      // Platform data is read-only here and a mounted app is usually one
-      // screen; refetching on every focus change is noise, not freshness.
-      defaultOptions: { queries: { refetchOnWindowFocus: false, retry: 1 } },
-    })
-
   root.render(
     <StrictMode>
-      <QueryClientProvider client={queryClient}>
-        <FronteraRoot session={session} app={app} providers={options.providers ?? []} />
-      </QueryClientProvider>
+      <FronteraAppProvider
+        providers={options.providers}
+        queryClient={options.queryClient}
+        timeoutMs={options.timeoutMs}
+      >
+        {app}
+      </FronteraAppProvider>
     </StrictMode>,
   )
 }

package/src/react.ts

@@ -0,0 +1,8 @@
+export {
+  FronteraAppProvider,
+  useFronteraApp,
+  type FronteraAppProviderProps,
+  type FronteraAppValue,
+  type FronteraProvider,
+} from './create-frontera-app'
+export type { FronteraAppMode } from './app-session'

package/src/transport.ts

@@ -10,6 +10,15 @@ export interface RequestOptions {
   body?: unknown
   query?: Record<string, string | number | boolean | undefined>
   signal?: AbortSignal
+  /**
+   * Extra headers for ONE request. Added for `idempotency-key`, which the
+   * governed write plane reads from the header rather than the body — a key in
+   * the payload would be part of the invocation it is meant to deduplicate.
+   *
+   * Auth is not overridable: the credential headers are applied after these, so
+   * a caller cannot swap the principal by passing `authorization` here.
+   */
+  headers?: Record<string, string>
 }
 
 /**
@@ -50,6 +59,13 @@ export function unwrap<T>(body: unknown): T {
   return body as T
 }
 
+function lowerCasedKeys(headers: Record<string, string> | undefined): Record<string, string> {
+  if (!headers) return {}
+  return Object.fromEntries(
+    Object.entries(headers).map(([name, value]) => [name.toLowerCase(), value]),
+  )
+}
+
 function buildUrl(config: FronteraConfig, path: string, query?: RequestOptions['query']): string {
   const url = new URL(`${config.apiBaseUrl}${path.startsWith('/') ? path : `/${path}`}`)
   if (query) {
@@ -71,7 +87,20 @@ export async function httpRequest<T>(
   options: RequestOptions = {},
   fetchImpl: typeof fetch = fetch,
 ): Promise<T> {
-  const headers: Record<string, string> = { ...authHeaders(config), accept: 'application/json' }
+  // Caller headers first, so the credential and content type below win. A
+  // request that could overwrite `authorization` would let any call site act as
+  // another principal, which is precisely what the transport exists to prevent.
+  //
+  // Lower-cased on the way in, because "later key wins" is a property of the
+  // OBJECT and header names are case-insensitive on the wire: `Authorization`
+  // and `authorization` are two distinct properties here and one name to
+  // `Headers`, which COMBINES them into `forged, real` rather than letting the
+  // credential replace the forgery.
+  const headers: Record<string, string> = {
+    ...lowerCasedKeys(options.headers),
+    ...authHeaders(config),
+    accept: 'application/json',
+  }
   if (options.body !== undefined) headers['content-type'] = 'application/json'
 
   const response = await fetchImpl(buildUrl(config, path, options.query), {