@frontera-sdk/core 1.50.84 → 1.51.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/core",
-  "version": "1.50.84",
+  "version": "1.51.0",
   "description": "Frontera app runtime: the platform bridge client, app bootstrap and typed platform client.",
   "keywords": [
     "frontera",

package/src/create-frontera-app.tsx

@@ -22,7 +22,13 @@ import {
   type FronteraAppMode,
 } from './app-session'
 import { applyHostTheme } from './theme'
-import { connectExternalSession, type ExternalAppSessionConfig } from './external-session'
+import {
+  connectExternalSession,
+  isAccessRefusal,
+  type AccessRefusal,
+  type AccessRefusalReason,
+  type ExternalAppSessionConfig,
+} from './external-session'
 
 /**
  * The entry point every app shares.
@@ -368,6 +374,98 @@ function diagnostic(title: string, detail: string, variant: 'loading' | 'error'
   )
 }
 
+/**
+ * What a person Frontera refused reads, one entry per refusal of the person.
+ * Plain and calm: this is not a crash, and the next step is someone else's.
+ */
+const ACCESS_COPY: Record<AccessRefusalReason, { title: string; detail: string }> = {
+  no_role: {
+    title: "You don't have access yet",
+    detail: "You don't have access to this App yet. Ask your administrator to give you a role.",
+  },
+  not_admitted: {
+    title: "You can't use this App",
+    detail: "Your account isn't allowed to sign in to this App. If you need it, ask your administrator.",
+  },
+  disabled: {
+    title: 'Your access is turned off',
+    detail: 'Your access to this App has been turned off. Ask your administrator if you need it back.',
+  },
+  not_linked: {
+    title: "We couldn't find your record",
+    detail: "This App couldn't match you to a record. Ask your administrator to link your account.",
+  },
+  link_ambiguous: {
+    title: 'Your account needs a quick fix',
+    detail: 'More than one record matches you. Ask your administrator to choose the right one.',
+  },
+}
+
+/**
+ * The default screen for a person Frontera refused to sign in: a title, one
+ * sentence on what to do, and Try again. Deliberately unlike `diagnostic`'s
+ * error variant (no alert icon, no monospaced message) because nothing is
+ * broken. The service's own message stays out: it is written for the App's
+ * builder, not the person.
+ */
+function accessRefusedScreen(error: AccessRefusal, retry: () => void): ReactNode {
+  const copy = ACCESS_COPY[error.reason]
+  return (
+    <div
+      role="status"
+      data-frontera-access-refused={error.reason}
+      style={{
+        boxSizing: 'border-box',
+        minHeight: '100dvh',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        padding: 32,
+        fontFamily: 'var(--font-sans, system-ui, sans-serif)',
+        background: BOOT_PALETTE.background,
+        lineHeight: 1.5,
+      }}
+    >
+      <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 10, textAlign: 'center', maxWidth: 380 }}>
+        <svg
+          aria-hidden="true"
+          viewBox="0 0 24 24"
+          width={30}
+          height={30}
+          fill="none"
+          stroke={BOOT_PALETTE.muted}
+          strokeWidth={2}
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          style={{ marginBottom: 6 }}
+        >
+          <rect x="5" y="11" width="14" height="10" rx="2" />
+          <path d="M8 11V7a4 4 0 0 1 8 0v4" />
+        </svg>
+        <div style={{ fontWeight: 'bold' as const, fontSize: 18 }}>{copy.title}</div>
+        <div style={{ fontSize: 14, color: BOOT_PALETTE.muted }}>{copy.detail}</div>
+        <button
+          type="button"
+          onClick={retry}
+          style={{
+            marginTop: 6,
+            padding: '6px 14px',
+            font: 'inherit',
+            fontSize: 14,
+            color: 'inherit',
+            background: BOOT_PALETTE.surface,
+            border: `1px solid ${BOOT_PALETTE.border}`,
+            borderRadius: 'calc(var(--radius, 8px) - 2px)',
+            cursor: 'pointer',
+          }}
+        >
+          Try again
+        </button>
+      </div>
+    </div>
+  )
+}
+
 /**
  * Holds what the host can change underneath a running app.
  *
@@ -446,7 +544,18 @@ export interface FronteraAppProviderProps {
   children: ReactNode
   providers?: FronteraProvider[]
   loading?: ReactNode
+  /** Shown when the App cannot start or crashes while rendering. */
   errorFallback?: (error: Error) => ReactNode
+  /**
+   * External Apps only: shown instead of the App when Frontera refuses the
+   * person, at start or when a later renewal is refused. `error.reason` is
+   * one of `no_role`, `not_admitted`, `disabled`, `not_linked` or
+   * `link_ambiguous`. `retry` signs in again. The default is a plain screen
+   * that tells the person to ask their administrator. Every other sign-in
+   * failure (a fault in the App's setup, `invalid_token`,
+   * `issuer_unreachable`, no reason) still reaches `errorFallback`.
+   */
+  accessDenied?: (error: AccessRefusal, retry: () => void) => ReactNode
   /** Compatibility hooks used by createFronteraApp. */
   queryClient?: QueryClient
   timeoutMs?: number
@@ -469,6 +578,7 @@ export function FronteraAppProvider({
   providers = [],
   loading = diagnostic('Connecting to Frontera', 'Establishing an authenticated App session.', 'loading'),
   errorFallback,
+  accessDenied = accessRefusedScreen,
   queryClient: providedQueryClient,
   timeoutMs,
   session: externalSession,
@@ -485,6 +595,16 @@ export function FronteraAppProvider({
         defaultOptions: { queries: { refetchOnWindowFocus: false, retry: 1 } },
       }),
   )
+  // Bumped by Try again on the access screen: signs in from scratch. The
+  // cache is emptied first, so the App never shows rows read by the session
+  // that was refused.
+  const [attempt, setAttempt] = useState(0)
+  const retry = useCallback(() => {
+    queryClient.clear()
+    setConnection(null)
+    setError(null)
+    setAttempt((n) => n + 1)
+  }, [queryClient])
 
   useEffect(() => {
     const runtime = readRuntimeGlobal()
@@ -508,7 +628,18 @@ export function FronteraAppProvider({
     let active = true
     let sessionToDispose: BridgeSession | null = null
     const connected: Promise<BridgeSession> = externalSession
-      ? connectExternalSession(externalSession)
+      ? connectExternalSession(externalSession).then((session) => {
+          // Mid-session: signing in again was refused (a role removed, the
+          // person disabled). The App's data is no longer theirs to see.
+          session.onRefused((refusal) => {
+            if (!active) return
+            session.dispose()
+            queryClient.clear()
+            setConnection(null)
+            setError(refusal)
+          })
+          return session
+        })
       : mode === 'embedded'
         ? connectToHost({ parentOrigin: runtime.platformOrigin, timeoutMs })
         : connectToSessionEndpoint(
@@ -534,9 +665,10 @@ export function FronteraAppProvider({
     }
     // 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.
-  }, [])
+    // reconnect. Only Try again (`attempt`) starts another.
+  }, [attempt])
 
+  if (isAccessRefusal(error)) return accessDenied(error, retry)
   if (error) return errorFallback?.(error) ?? diagnostic('Frontera App could not start', error.message)
   if (!connection) return loading
 

package/src/external-session.ts

@@ -61,6 +61,29 @@ export class AppUserSignInError extends Error {
   }
 }
 
+/**
+ * The refusals that are about the person: Frontera knows who they are and
+ * will not let them in. Signing in again gives the same answer until an
+ * administrator changes something, so a running session stops renewing and
+ * the App shows the refusal.
+ *
+ * An allow-list, so a reason added to the service later is not shown to
+ * people as "you have no access" by accident. Everything else is the App's
+ * to handle as before: a fault in the App's setup (`app_not_found`,
+ * `audience_disabled`, `key_invalid`, `audience_misconfigured`), a token that
+ * did not verify (`invalid_token`: the App may need to send the person to its
+ * login), the identity provider being down (`issuer_unreachable`), and a
+ * failure with no reason (a rate limit, a server fault, the App's own session
+ * endpoint).
+ */
+export const ACCESS_REFUSAL_REASONS = ['no_role', 'not_admitted', 'disabled', 'not_linked', 'link_ambiguous'] as const
+export type AccessRefusalReason = (typeof ACCESS_REFUSAL_REASONS)[number]
+export type AccessRefusal = AppUserSignInError & { readonly reason: AccessRefusalReason }
+
+export function isAccessRefusal(error: unknown): error is AccessRefusal {
+  return error instanceof AppUserSignInError && (ACCESS_REFUSAL_REASONS as readonly (string | null)[]).includes(error.reason)
+}
+
 type FetchImpl = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>
 
 function unwrap(body: unknown): Record<string, unknown> {
@@ -145,17 +168,28 @@ const MIN_RENEW_DELAY_MS = 30_000
 const FIRST_BACKOFF_MS = 30_000
 const MAX_BACKOFF_MS = 5 * 60_000
 
+export interface ExternalSession extends BridgeSession {
+  appUser: AppUserSummary | null
+  /**
+   * Called once when signing in again is refused for the person's own reason
+   * (see `isAccessRefusal`). The session has stopped renewing by then.
+   */
+  onRefused(handler: (error: AccessRefusal) => void): () => void
+}
+
 /**
  * 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.
+ * passes, no request triggers another, so an unreachable identity provider
+ * costs one attempt per backoff step, not one per request. Only a refusal of
+ * the person (`isAccessRefusal`: no role, disabled, …) ends renewal for good
+ * and is reported to `onRefused`.
  */
 export async function connectExternalSession(
   config: ExternalAppSessionConfig,
   options: ExternalSessionOptions = {},
-): Promise<BridgeSession & { appUser: AppUserSummary | null }> {
+): Promise<ExternalSession> {
   const fetchImpl = options.fetchImpl ?? fetch
   const now = options.now ?? Date.now
   const setTimer = options.setTimer ?? ((callback, delay) => setTimeout(callback, delay))
@@ -163,6 +197,8 @@ export async function connectExternalSession(
 
   const first = await nextToken(config, fetchImpl, now)
   const tokenHandlers = new Set<(token: string) => void>()
+  const refusalHandlers = new Set<(error: AccessRefusal) => void>()
+  let refused: AccessRefusal | null = null
   let disposed = false
   let timer: unknown
   let currentToken = first.token
@@ -195,7 +231,7 @@ export async function connectExternalSession(
    * share one exchange.
    */
   const renewNow = (): Promise<string | null> => {
-    if (disposed) return Promise.resolve(null)
+    if (disposed || refused) return Promise.resolve(null)
     if (renewing) return renewing
     if (now() < retryAfter) return Promise.resolve(null)
     renewing = nextToken(config, fetchImpl, now)
@@ -207,7 +243,15 @@ export async function connectExternalSession(
         schedule(next.expiresAt)
         return next.token
       })
-      .catch(() => {
+      .catch((error: unknown) => {
+        if (disposed) return null
+        if (isAccessRefusal(error)) {
+          refused = error
+          if (timer !== undefined) clearTimer(timer)
+          timer = undefined
+          for (const handler of refusalHandlers) handler(error)
+          return null
+        }
         const backoff = Math.min(MAX_BACKOFF_MS, FIRST_BACKOFF_MS * 2 ** failures)
         failures++
         retryAfter = now() + backoff
@@ -263,6 +307,14 @@ export async function connectExternalSession(
       tokenHandlers.add(handler)
       return () => tokenHandlers.delete(handler)
     },
+    onRefused(handler) {
+      if (refused) {
+        handler(refused)
+        return () => {}
+      }
+      refusalHandlers.add(handler)
+      return () => refusalHandlers.delete(handler)
+    },
     onTheme() {
       return () => {}
     },
@@ -273,6 +325,7 @@ export async function connectExternalSession(
       disposed = true
       if (timer !== undefined) clearTimer(timer)
       tokenHandlers.clear()
+      refusalHandlers.clear()
     },
   }
 }

package/src/react.ts

@@ -11,6 +11,9 @@ export type { FronteraViewer } from './bridge-protocol'
 export {
   AppUserSignInError,
   exchangeCustomerToken,
+  isAccessRefusal,
+  type AccessRefusal,
+  type AccessRefusalReason,
   type AppUserSummary,
   type ExternalAppSessionConfig,
 } from './external-session'