@frontera-sdk/core 1.50.79 → 1.50.80

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/core",
-  "version": "1.50.79",
+  "version": "1.50.80",
   "description": "Frontera app runtime: the platform bridge client, app bootstrap and typed platform client.",
   "keywords": [
     "frontera",
@@ -57,6 +57,14 @@
       "types": "./src/create-frontera-app.tsx",
       "import": "./src/create-frontera-app.tsx"
     },
+    "./external-session": {
+      "types": "./src/external-session.ts",
+      "import": "./src/external-session.ts"
+    },
+    "./app-session": {
+      "types": "./src/app-session.ts",
+      "import": "./src/app-session.ts"
+    },
     "./react": {
       "types": "./src/react.ts",
       "import": "./src/react.ts"

package/src/bridge-client.ts

@@ -25,6 +25,12 @@ export interface BridgeSession {
   /** Visibility changes do not revoke credentials or imply execution is paused. */
   onActivation(handler: (active: boolean) => void): () => void
   dispose(): void
+  /**
+   * The fetch the App's API client should use, when the session needs a say in
+   * its requests — an externally hosted App re-signs in and retries once when
+   * the service refuses a token that was revoked early. Absent: plain fetch.
+   */
+  fetchImpl?: typeof fetch
 }
 
 export interface ConnectOptions {

package/src/create-frontera-app.tsx

@@ -22,6 +22,7 @@ import {
   type FronteraAppMode,
 } from './app-session'
 import { applyHostTheme } from './theme'
+import { connectExternalSession, type ExternalAppSessionConfig } from './external-session'
 
 /**
  * The entry point every app shares.
@@ -379,7 +380,7 @@ function FronteraRoot({
         orgId: init.orgId ?? undefined,
         workspaceId: init.workspaceId ?? undefined,
         credential: { kind: 'token', token: init.token },
-      }),
+      }, session.fetchImpl),
   )
 
   useEffect(
@@ -432,6 +433,13 @@ export interface FronteraAppProviderProps {
   /** Compatibility hooks used by createFronteraApp. */
   queryClient?: QueryClient
   timeoutMs?: number
+  /**
+   * For an App hosted OUTSIDE Frontera: how its people sign in. Given, the
+   * provider does not look for a platform frame or a session endpoint — it
+   * exchanges the customer's identity-provider token (or calls your backend)
+   * for a Frontera App-user token and renews it before it expires.
+   */
+  session?: ExternalAppSessionConfig
 }
 
 /**
@@ -446,6 +454,7 @@ export function FronteraAppProvider({
   errorFallback,
   queryClient: providedQueryClient,
   timeoutMs,
+  session: externalSession,
 }: FronteraAppProviderProps): ReactNode {
   const [connection, setConnection] = useState<{
     mode: FronteraAppMode
@@ -463,7 +472,9 @@ export function FronteraAppProvider({
   useEffect(() => {
     const runtime = readRuntimeGlobal()
     const framed = typeof window !== 'undefined' && window.parent !== window
-    const mode = detectAppMode(runtime, framed)
+    // An externally hosted App names its session explicitly; nothing else is
+    // consulted, so a stray frame or leftover global cannot redirect it.
+    const mode = externalSession ? 'standalone' : detectAppMode(runtime, framed)
     if (!mode) {
       // Reachable only when NOT framed: `detectAppMode` returns 'embedded' for
       // any framed document, so a null mode means there is no parent and no
@@ -479,8 +490,9 @@ export function FronteraAppProvider({
 
     let active = true
     let sessionToDispose: BridgeSession | null = null
-    const connected =
-      mode === 'embedded'
+    const connected: Promise<BridgeSession> = externalSession
+      ? connectExternalSession(externalSession)
+      : mode === 'embedded'
         ? connectToHost({ parentOrigin: runtime.platformOrigin, timeoutMs })
         : connectToSessionEndpoint(
             mode === 'standalone' ? runtime.sessionEndpoint! : runtime.devSessionEndpoint!,
@@ -503,6 +515,9 @@ export function FronteraAppProvider({
       active = false
       sessionToDispose?.dispose()
     }
+    // Read once at mount, like the runtime global: a session is established
+    // for the page's life, and a new config object each render must not
+    // reconnect.
   }, [])
 
   if (error) return errorFallback?.(error) ?? diagnostic('Frontera App could not start', error.message)

package/src/external-session.ts

@@ -0,0 +1,278 @@
+import type { BridgeSession } from './bridge-client'
+import type { BridgeInit } from './bridge-protocol'
+
+/**
+ * A session for an App hosted OUTSIDE Frontera, whose people sign in with the
+ * customer's own identity provider (design docs/specs/2026-09-24-app-users-design.md
+ * §7, §15).
+ *
+ * Two ways to get the Frontera App-user token, and the App picks one:
+ *
+ *   - `getSubjectToken` — the browser holds the customer's identity-provider
+ *     token (their OIDC client already signed the person in) and exchanges it
+ *     directly at `POST /v1/app-users/token`.
+ *   - `sessionEndpoint` — the App's own backend makes the exchange with an App
+ *     key and returns `{ token, expiresAt }`. The key never reaches the page.
+ *
+ * Either way the page only ever holds the short-lived App-user token, renewed
+ * before it expires.
+ */
+export interface ExternalAppSessionConfig {
+  /** Frontera's API origin, e.g. `https://api.frontera.example`. */
+  apiBaseUrl: string
+  /** The External App's id. */
+  appId: string
+  /** Which of the App's audiences this page signs people into. Default `operator`. */
+  audience?: 'operator' | 'customer'
+  /** The customer's current identity-provider token (browser exchange). */
+  getSubjectToken?: () => Promise<string>
+  /** Or: your backend route that exchanges with an App key and returns `{ token, expiresAt }`. */
+  sessionEndpoint?: string
+}
+
+export interface AppUserSummary {
+  id: string
+  displayName: string | null
+  audience: 'operator' | 'customer'
+  roles: string[]
+  attributes: Record<string, unknown>
+  businessObject: { objectType: string; id: string } | null
+}
+
+export interface ExchangedToken {
+  token: string
+  /**
+   * Epoch ms, on THIS machine's clock: taken from the service's `expiresIn`
+   * when it sends one, so a browser clock that is off never makes renewal loop.
+   */
+  expiresAt: number
+  appUser?: AppUserSummary
+}
+
+export class AppUserSignInError extends Error {
+  constructor(
+    message: string,
+    /** Frontera's stable reason, e.g. `not_admitted`, `not_linked`, `disabled`. */
+    readonly reason: string | null,
+    readonly status: number,
+  ) {
+    super(message)
+    this.name = 'AppUserSignInError'
+  }
+}
+
+type FetchImpl = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>
+
+function unwrap(body: unknown): Record<string, unknown> {
+  const envelope = body as { data?: unknown } | null
+  const data = envelope && typeof envelope === 'object' && 'data' in envelope ? envelope.data : body
+  return (data && typeof data === 'object' ? data : {}) as Record<string, unknown>
+}
+
+function expiryOf(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 sign-in response has an invalid expiresAt')
+  return parsed
+}
+
+async function readToken(response: Response, now: () => number = Date.now): Promise<ExchangedToken> {
+  const body = await response.json().catch(() => null) as Record<string, unknown> | null
+  if (!response.ok) {
+    const details = (body?.details ?? null) as { reason?: string } | null
+    throw new AppUserSignInError(
+      typeof body?.message === 'string' ? body.message : `Frontera sign-in failed with ${response.status}`,
+      details?.reason ?? null,
+      response.status,
+    )
+  }
+  const data = unwrap(body)
+  if (typeof data.token !== 'string') throw new Error('Frontera sign-in response has no token')
+  return {
+    token: data.token,
+    expiresAt: typeof data.expiresIn === 'number' && Number.isFinite(data.expiresIn)
+      ? now() + data.expiresIn * 1000
+      : expiryOf(data.expiresAt),
+    ...(data.appUser ? { appUser: data.appUser as AppUserSummary } : {}),
+  }
+}
+
+/** Exchange a customer identity-provider token for a Frontera App-user token. */
+export async function exchangeCustomerToken(
+  input: { apiBaseUrl: string; appId: string; audience?: 'operator' | 'customer'; subjectToken: string },
+  fetchImpl: FetchImpl = fetch,
+  now: () => number = Date.now,
+): Promise<ExchangedToken> {
+  const response = await fetchImpl(`${input.apiBaseUrl.replace(/\/+$/, '')}/v1/app-users/token`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', accept: 'application/json' },
+    body: JSON.stringify({
+      grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange',
+      app: input.appId,
+      audience: input.audience ?? 'operator',
+      subject_token: input.subjectToken,
+      subject_token_type: 'urn:ietf:params:oauth:token-type:jwt',
+    }),
+  })
+  return readToken(response, now)
+}
+
+async function nextToken(config: ExternalAppSessionConfig, fetchImpl: FetchImpl, now: () => number): Promise<ExchangedToken> {
+  if (config.getSubjectToken) {
+    return exchangeCustomerToken({
+      apiBaseUrl: config.apiBaseUrl,
+      appId: config.appId,
+      audience: config.audience,
+      subjectToken: await config.getSubjectToken(),
+    }, fetchImpl, now)
+  }
+  if (config.sessionEndpoint) {
+    const response = await fetchImpl(config.sessionEndpoint, { credentials: 'include', headers: { accept: 'application/json' } })
+    return readToken(response, now)
+  }
+  throw new Error('An external App session needs getSubjectToken or sessionEndpoint.')
+}
+
+export interface ExternalSessionOptions {
+  fetchImpl?: FetchImpl
+  now?: () => number
+  setTimer?: (callback: () => void, delay: number) => unknown
+  clearTimer?: (timer: unknown) => void
+}
+
+/** Never renew sooner than this after a token arrives. */
+const MIN_RENEW_DELAY_MS = 30_000
+/** After a failed sign-in, wait this long before the next, doubling to the cap. */
+const FIRST_BACKOFF_MS = 30_000
+const MAX_BACKOFF_MS = 5 * 60_000
+
+/**
+ * A bridge-compatible session for an externally hosted App: signs in once,
+ * then renews the App-user token at 80% of its life. A request refused with
+ * 401 signs in again once. A failed sign-in is remembered: until its backoff
+ * passes, no request triggers another, so a disabled person or an unreachable
+ * identity provider costs one attempt per backoff step, not one per request.
+ */
+export async function connectExternalSession(
+  config: ExternalAppSessionConfig,
+  options: ExternalSessionOptions = {},
+): Promise<BridgeSession & { appUser: AppUserSummary | null }> {
+  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 nextToken(config, fetchImpl, now)
+  const tokenHandlers = new Set<(token: string) => void>()
+  let disposed = false
+  let timer: unknown
+  let currentToken = first.token
+  // One renewal at a time: several requests refused together share it.
+  let renewing: Promise<string | null> | null = null
+  let failures = 0
+  let retryAfter = 0
+
+  const publish = (token: string) => {
+    currentToken = token
+    for (const handler of tokenHandlers) handler(token)
+  }
+
+  // One timer at a time: scheduling replaces any pending one, so a renewal
+  // from a 401 and a scheduled one can never leave two chains running.
+  const scheduleIn = (delay: number) => {
+    if (timer !== undefined) clearTimer(timer)
+    timer = undefined
+    if (disposed) return
+    timer = setTimer(() => {
+      timer = undefined
+      void renewNow()
+    }, delay)
+  }
+  const schedule = (expiresAt: number) => scheduleIn(Math.max(MIN_RENEW_DELAY_MS, Math.floor((expiresAt - now()) * 0.8)))
+
+  /**
+   * Sign in again now: on schedule, or because the service refused the current
+   * token (revoked, or settings changed). Single-flight — concurrent callers
+   * share one exchange.
+   */
+  const renewNow = (): Promise<string | null> => {
+    if (disposed) return Promise.resolve(null)
+    if (renewing) return renewing
+    if (now() < retryAfter) return Promise.resolve(null)
+    renewing = nextToken(config, fetchImpl, now)
+      .then((next) => {
+        if (disposed) return null
+        failures = 0
+        retryAfter = 0
+        publish(next.token)
+        schedule(next.expiresAt)
+        return next.token
+      })
+      .catch(() => {
+        const backoff = Math.min(MAX_BACKOFF_MS, FIRST_BACKOFF_MS * 2 ** failures)
+        failures++
+        retryAfter = now() + backoff
+        scheduleIn(backoff)
+        return null
+      })
+      .finally(() => { renewing = null })
+    return renewing
+  }
+  schedule(first.expiresAt)
+
+  /**
+   * Requests to Frontera go through here. A 401 on a request that carried the
+   * App-user token means it was refused before it expired — the person was
+   * disabled, or the audience's settings changed. Sign in again once and retry
+   * the request with the new token; a second refusal stands.
+   */
+  const apiFetch: typeof fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const response = await fetchImpl(input, init)
+    const headers = new Headers(init?.headers)
+    const sent = headers.get('authorization')
+    // Only a request that carried an App-user token is ours to retry.
+    if (response.status !== 401 || !sent?.startsWith('Bearer sk-au-')) return response
+    const renewed = await renewNow()
+    if (!renewed) return response
+    headers.set('authorization', `Bearer ${renewed}`)
+    return fetchImpl(input, { ...init, headers })
+  }) as typeof fetch
+
+  const init: BridgeInit = {
+    type: 'frontera:init',
+    token: first.token,
+    apiBaseUrl: config.apiBaseUrl.replace(/\/+$/, ''),
+    appId: config.appId,
+    version: 'external',
+    // The App-user token names its organization and workspace itself; the
+    // service reads them from the token, never from a header.
+    orgId: null,
+    workspaceId: null,
+    theme: { tokens: {} },
+    state: {},
+  }
+
+  return {
+    init,
+    appUser: first.appUser ?? null,
+    fetchImpl: apiFetch,
+    send() {},
+    onState() {
+      return () => {}
+    },
+    onToken(handler) {
+      tokenHandlers.add(handler)
+      return () => tokenHandlers.delete(handler)
+    },
+    onTheme() {
+      return () => {}
+    },
+    onActivation() {
+      return () => {}
+    },
+    dispose() {
+      disposed = true
+      if (timer !== undefined) clearTimer(timer)
+      tokenHandlers.clear()
+    },
+  }
+}

package/src/react.ts

@@ -6,3 +6,9 @@ export {
   type FronteraProvider,
 } from './create-frontera-app'
 export type { FronteraAppMode } from './app-session'
+export {
+  AppUserSignInError,
+  exchangeCustomerToken,
+  type AppUserSummary,
+  type ExternalAppSessionConfig,
+} from './external-session'