@sanity/sdk 3.3.0-rc.1 → 3.3.0

package/src/auth/oauth/oauthActions.ts

@@ -17,25 +17,6 @@ export const OAUTH_VERIFIER_KEY = '__sanity_oauth_verifier'
 /** sessionStorage key for the CSRF `state` value. */
 export const OAUTH_STATE_KEY = '__sanity_oauth_state'
 
-/** sessionStorage key for the location to return to after the callback. */
-export const OAUTH_RETURN_TO_KEY = '__sanity_oauth_return_to'
-
-const OAUTH_CALLBACK_PARAMS = ['code', 'state', 'error', 'error_description']
-
-/** Strips the OAuth callback params from a URL. */
-function stripOAuthParams(href: string): string {
-  const url = new URL(href, DEFAULT_BASE)
-  for (const param of OAUTH_CALLBACK_PARAMS) url.searchParams.delete(param)
-  return url.toString()
-}
-
-/** Whether `href` is the registered redirect URI (origin + pathname; query and hash ignored). */
-function isCallbackRoute(href: string, redirectUri: string): boolean {
-  const current = new URL(href, DEFAULT_BASE)
-  const redirect = new URL(redirectUri, DEFAULT_BASE)
-  return current.origin === redirect.origin && current.pathname === redirect.pathname
-}
-
 interface TokenEndpointResponse {
   access_token: string
   token_type: string
@@ -48,19 +29,6 @@ function getResourceIndicator(organizationId: string): string {
   return `urn:io.sanity:organization:${organizationId}`
 }
 
-/**
- * Appends the RFC 8707 `resource` indicator to `params` when an organisation
- * id is configured. Without one, the request is left unscoped.
- */
-function appendResourceIndicator(
-  params: URLSearchParams,
-  oauth: NonNullable<AuthOptions['oauth']>,
-): void {
-  if (oauth.organizationId) {
-    params.append('resource', getResourceIndicator(oauth.organizationId))
-  }
-}
-
 /**
  * Serialises tokens for storage, converting `expiresAt` to an ISO string.
  *
@@ -102,21 +70,6 @@ function createOAuthClient(options: AuthOptions): SanityClient {
   })
 }
 
-/** POSTs form-encoded params to the OAuth token endpoint. */
-function postTokenRequest(
-  client: SanityClient,
-  params: URLSearchParams,
-  tag: string,
-): Promise<TokenEndpointResponse> {
-  return client.request<TokenEndpointResponse>({
-    method: 'POST',
-    url: '/auth/oauth/token',
-    headers: {'content-type': 'application/x-www-form-urlencoded'},
-    body: params.toString(),
-    tag,
-  })
-}
-
 /** Converts a token endpoint response to the {@link OAuthTokens} shape. */
 function toOAuthTokens(response: TokenEndpointResponse): OAuthTokens {
   return {
@@ -146,17 +99,6 @@ export const startOAuthAuthorization = bindActionGlobally(authStore, async ({sta
   const session = typeof sessionStorage !== 'undefined' ? sessionStorage : undefined
   session?.setItem(OAUTH_VERIFIER_KEY, codeVerifier)
   session?.setItem(OAUTH_STATE_KEY, oauthState)
-  // The redirect URI must match the registered one exactly, so the current
-  // location (deep link) is stashed here and restored by the callback. OAuth
-  // params are only stripped when we are already on the callback route, so
-  // legitimate app params like `?state=draft` survive the round trip.
-  const currentHref = getDefaultLocation()
-  if (currentHref !== DEFAULT_BASE) {
-    const returnTo = isCallbackRoute(currentHref, options.oauth.redirectUri)
-      ? stripOAuthParams(currentHref)
-      : currentHref
-    session?.setItem(OAUTH_RETURN_TO_KEY, returnTo)
-  }
 
   const authorizeUrl = new URL(
     '/v1/auth/oauth/authorize',
@@ -168,7 +110,7 @@ export const startOAuthAuthorization = bindActionGlobally(authStore, async ({sta
   authorizeUrl.searchParams.set('state', oauthState)
   authorizeUrl.searchParams.set('code_challenge', codeChallenge)
   authorizeUrl.searchParams.set('code_challenge_method', 'S256')
-  appendResourceIndicator(authorizeUrl.searchParams, options.oauth)
+  authorizeUrl.searchParams.append('resource', getResourceIndicator(options.oauth.organizationId))
 
   logger.info('Starting OAuth authorization')
   if (typeof window !== 'undefined' && typeof window.location?.assign === 'function') {
@@ -181,14 +123,9 @@ export const startOAuthAuthorization = bindActionGlobally(authStore, async ({sta
  * responses, exchanges the authorization `code` for tokens, persists them, and
  * transitions to `LOGGED_IN`.
  *
- * Returns the URL for the caller to `history.replaceState` to when a callback
- * was processed: on success, the same-origin location the user was on when
- * the flow started (if any), otherwise the callback URL cleaned of OAuth
- * params. Returns `false` when there was nothing to handle (no code, or an
- * exchange already in progress). A callback that fails validation while a
- * session is already `LOGGED_IN` (e.g. a remount before the params were
- * stripped) is ignored with a warning and still returns the cleaned URL, so a
- * string result does not imply an exchange ran.
+ * Returns the callback URL cleaned of OAuth params (for the caller to
+ * `history.replaceState`) when a callback was processed, or `false` when there
+ * was nothing to handle (no code, or an exchange already in progress).
  *
  * @public
  */
@@ -215,29 +152,22 @@ export const handleOAuthCallback = bindActionGlobally(
 
     const session = typeof sessionStorage !== 'undefined' ? sessionStorage : undefined
 
-    const cleanedUrl = stripOAuthParams(locationHref)
-
-    // Callback failures move to ERROR, unless a session is already
-    // established: a stale callback URL (e.g. remount before the params were
-    // stripped, after the artifacts were cleared) or a denied re-authorization
-    // must not clobber LOGGED_IN.
-    const rejectCallback = (name: string, message: string): string => {
-      if (authState.type === AuthStateType.LOGGED_IN) {
-        // Leave PKCE artifacts alone: a re-authorization may be in flight.
-        logger.warn(`${message} — ignoring callback, session already established`)
-        return cleanedUrl
-      }
-      logger.error(`${message} — rejecting callback`)
-      clearOAuthArtifacts(session)
-      state.set(name, {authState: {type: AuthStateType.ERROR, error: new Error(message)}})
-      return cleanedUrl
+    const cleanedUrlObj = new URL(locationHref, DEFAULT_BASE)
+    for (const param of ['code', 'state', 'error', 'error_description']) {
+      cleanedUrlObj.searchParams.delete(param)
     }
+    const cleanedUrl = cleanedUrlObj.toString()
 
     if (error) {
-      return rejectCallback(
-        'oauthCallbackError',
-        errorDescription ? `${error}: ${errorDescription}` : error,
-      )
+      logger.warn('OAuth callback returned an error', {error, errorDescription})
+      clearOAuthArtifacts(session)
+      state.set('oauthCallbackError', {
+        authState: {
+          type: AuthStateType.ERROR,
+          error: new Error(errorDescription ? `${error}: ${errorDescription}` : error),
+        },
+      })
+      return cleanedUrl
     }
 
     if (!code) {
@@ -247,12 +177,22 @@ export const handleOAuthCallback = bindActionGlobally(
 
     const storedState = session?.getItem(OAUTH_STATE_KEY) ?? null
     if (!returnedState || !storedState || returnedState !== storedState) {
-      return rejectCallback('oauthStateMismatch', 'OAuth state mismatch')
+      logger.error('OAuth state mismatch — rejecting callback')
+      clearOAuthArtifacts(session)
+      state.set('oauthStateMismatch', {
+        authState: {type: AuthStateType.ERROR, error: new Error('OAuth state mismatch')},
+      })
+      return cleanedUrl
     }
 
     const codeVerifier = session?.getItem(OAUTH_VERIFIER_KEY) ?? null
     if (!codeVerifier) {
-      return rejectCallback('oauthVerifierMissing', 'OAuth code verifier missing')
+      logger.error('OAuth code verifier missing — cannot exchange code')
+      clearOAuthArtifacts(session)
+      state.set('oauthVerifierMissing', {
+        authState: {type: AuthStateType.ERROR, error: new Error('OAuth code verifier missing')},
+      })
+      return cleanedUrl
     }
 
     logger.info('Exchanging OAuth code for tokens')
@@ -268,13 +208,18 @@ export const handleOAuthCallback = bindActionGlobally(
         code_verifier: codeVerifier,
         redirect_uri: options.oauth.redirectUri,
         client_id: options.oauth.clientId,
+        resource: getResourceIndicator(options.oauth.organizationId),
+      })
+      const response = await client.request<TokenEndpointResponse>({
+        method: 'POST',
+        url: '/auth/oauth/token',
+        headers: {'content-type': 'application/x-www-form-urlencoded'},
+        body: params.toString(),
+        tag: 'oauth.token',
       })
-      appendResourceIndicator(params, options.oauth)
-      const response = await postTokenRequest(client, params, 'oauth.token')
 
       const tokens = toOAuthTokens(response)
       options.storageArea?.setItem(options.storageKey, serializeTokens(tokens))
-      const returnTo = getSameOriginReturnTo(session, options.oauth.redirectUri)
       clearOAuthArtifacts(session)
 
       logger.info('OAuth tokens obtained, user logged in')
@@ -282,7 +227,7 @@ export const handleOAuthCallback = bindActionGlobally(
         authState: createLoggedInAuthState(tokens.accessToken, null),
         oauthTokens: tokens,
       })
-      return returnTo ?? cleanedUrl
+      return cleanedUrl
     } catch (exchangeError) {
       logger.error('Failed to exchange OAuth code for tokens', {error: exchangeError})
       clearOAuthArtifacts(session)
@@ -351,9 +296,15 @@ async function doRefreshOAuthTokens({
       grant_type: 'refresh_token',
       refresh_token: current.refreshToken,
       client_id: options.oauth.clientId,
+      resource: getResourceIndicator(options.oauth.organizationId),
+    })
+    const response = await client.request<TokenEndpointResponse>({
+      method: 'POST',
+      url: '/auth/oauth/token',
+      headers: {'content-type': 'application/x-www-form-urlencoded'},
+      body: params.toString(),
+      tag: 'oauth.refresh',
     })
-    appendResourceIndicator(params, options.oauth)
-    const response = await postTokenRequest(client, params, 'oauth.refresh')
 
     const tokens = toOAuthTokens(response)
     if (!tokens.refreshToken) tokens.refreshToken = current.refreshToken
@@ -435,20 +386,4 @@ export const getOAuthTokensState = bindActionGlobally(
 function clearOAuthArtifacts(session: Storage | undefined): void {
   session?.removeItem(OAUTH_VERIFIER_KEY)
   session?.removeItem(OAUTH_STATE_KEY)
-  session?.removeItem(OAUTH_RETURN_TO_KEY)
-}
-
-/**
- * Reads the stashed pre-authorize location, only honouring it when it shares
- * the registered redirect URI's origin so a tampered value cannot redirect
- * off-site. (`origin` includes the scheme, so non-http(s) URLs are rejected.)
- */
-function getSameOriginReturnTo(session: Storage | undefined, redirectUri: string): string | null {
-  const returnTo = session?.getItem(OAUTH_RETURN_TO_KEY) ?? null
-  if (!returnTo) return null
-  try {
-    return new URL(returnTo).origin === new URL(redirectUri).origin ? returnTo : null
-  } catch {
-    return null
-  }
 }

package/src/auth/oauth/oauthAuth.test.ts

@@ -83,11 +83,6 @@ describe('serialize/deserialize tokens', () => {
     expect(deserializeTokens('{"foo":"bar"}')).toBeNull()
     expect(deserializeTokens('123')).toBeNull()
   })
-
-  it('returns null when expiresAt does not parse to a valid date', () => {
-    const raw = JSON.stringify({...JSON.parse(serializeTokens(tokens)), expiresAt: 'garbage'})
-    expect(deserializeTokens(raw)).toBeNull()
-  })
 })
 
 describe('getOauthInitialState', () => {
@@ -99,16 +94,6 @@ describe('getOauthInitialState', () => {
     expect(result.authMethod).toBe('localstorage')
   })
 
-  it('returns LOGGED_OUT and clears storage when persisted tokens are corrupt', () => {
-    const storageArea = createMemoryStorage({
-      [OAUTH_TOKENS_KEY]: '{"accessToken":"a","expiresAt":"garbage"}',
-    })
-    const result = getOauthInitialState(baseOptions({storageArea}))
-    expect(result.authState).toEqual({type: AuthStateType.LOGGED_OUT, isDestroyingSession: false})
-    expect(result.oauthTokens).toBeUndefined()
-    expect(storageArea.getItem(OAUTH_TOKENS_KEY)).toBeNull()
-  })
-
   it('returns LOGGING_IN when the callback URL matches the redirect URI', () => {
     const storageArea = createMemoryStorage()
     const result = getOauthInitialState(
@@ -125,14 +110,6 @@ describe('getOauthInitialState', () => {
     expect(result.authState).toEqual({type: AuthStateType.LOGGED_OUT, isDestroyingSession: false})
   })
 
-  it('returns LOGGED_OUT when the redirect URI only carries a stray state param', () => {
-    const storageArea = createMemoryStorage()
-    const result = getOauthInitialState(
-      baseOptions({storageArea, initialLocationHref: 'https://app/callback?state=s'}),
-    )
-    expect(result.authState).toEqual({type: AuthStateType.LOGGED_OUT, isDestroyingSession: false})
-  })
-
   it('returns LOGGED_OUT when there are no tokens and no callback', () => {
     const storageArea = createMemoryStorage()
     const result = getOauthInitialState(baseOptions({storageArea}))

package/src/auth/oauth/oauthAuth.ts

@@ -19,9 +19,7 @@ interface SerializedOAuthTokens extends Omit<OAuthTokens, 'expiresAt'> {
 
 /**
  * Parses persisted token JSON back into {@link OAuthTokens}. Returns `null`
- * when the value is missing or malformed, including an `expiresAt` that does
- * not parse to a valid date (an `Invalid Date` would otherwise read as never
- * expiring, since `NaN <= now` is always `false`).
+ * when the value is missing or malformed.
  *
  * @internal
  */
@@ -40,13 +38,11 @@ export function deserializeTokens(raw: string | null): OAuthTokens | null {
       return null
     }
     const value = parsed as SerializedOAuthTokens
-    const expiresAt = new Date(value.expiresAt)
-    if (Number.isNaN(expiresAt.getTime())) return null
     return {
       accessToken: value.accessToken,
       tokenType: 'bearer',
       expiresIn: value.expiresIn,
-      expiresAt,
+      expiresAt: new Date(value.expiresAt),
       ...(value.refreshToken !== undefined && {refreshToken: value.refreshToken}),
     }
   } catch {
@@ -59,7 +55,7 @@ export function deserializeTokens(raw: string | null): OAuthTokens | null {
  *
  * State discovery order:
  * 1. Persisted tokens in `__sanity_oauth_tokens` → `LOGGED_IN`
- * 2. Callback URL (contains `code` or `error` and matches `redirectUri`)
+ * 2. Callback URL (contains `code`/`state`/`error` and matches `redirectUri`)
  *    → `LOGGING_IN`
  * 3. Otherwise → `LOGGED_OUT`
  *
@@ -72,12 +68,7 @@ export function getOauthInitialState(options: AuthStrategyOptions): AuthStrategy
   const redirectUri = authConfig.oauth?.redirectUri
 
   // Persisted tokens win
-  const rawTokens = storageArea?.getItem(OAUTH_TOKENS_KEY) ?? null
-  const tokens = deserializeTokens(rawTokens)
-  if (rawTokens && !tokens) {
-    // Corrupt entry: drop it so it cannot keep shadowing a fresh login
-    storageArea?.removeItem(OAUTH_TOKENS_KEY)
-  }
+  const tokens = deserializeTokens(storageArea?.getItem(OAUTH_TOKENS_KEY) ?? null)
   if (tokens) {
     return {
       authState: createLoggedInAuthState(tokens.accessToken, null),
@@ -89,12 +80,11 @@ export function getOauthInitialState(options: AuthStrategyOptions): AuthStrategy
     }
   }
 
-  // Callback URL with code/error whose origin + pathname match our redirect
-  // URI (query and hash are ignored). `state` alone is not a callback: the
-  // server always sends `code` or `error`, and handleOAuthCallback would
-  // otherwise leave the app stuck in LOGGING_IN.
+  // Callback URL with code/state/error whose origin + pathname match our
+  // redirect URI (query and hash are ignored).
   const {searchParams} = new URL(initialLocationHref, DEFAULT_BASE)
-  const isCallback = searchParams.has('code') || searchParams.has('error')
+  const isCallback =
+    searchParams.has('code') || searchParams.has('state') || searchParams.has('error')
   if (redirectUri && isCallback) {
     const loc = new URL(initialLocationHref, DEFAULT_BASE)
     const redirect = new URL(redirectUri, DEFAULT_BASE)

package/src/config/authConfig.ts

@@ -90,11 +90,8 @@ export interface AuthConfig {
     redirectUri: string
 
     /**
-     * Organisation id used for RFC 8707 resource scoping. Optional: when
-     * omitted, the `resource` parameter is left off the authorize and token
-     * requests, so the issued tokens are not restricted to a single
-     * organisation.
+     * Organisation id used for RFC 8707 resource scoping.
      */
-    organizationId?: string
+    organizationId: string
   }
 }

package/src/dashboard/messageBus/bus.test.ts

@@ -500,6 +500,45 @@ describe('application connections', () => {
     expect(app.subscribe('auth.token').getCurrent()).toBe('trusted')
   })
 
+  it('delivers application status events to the host and rejects app responders', () => {
+    const statusHost = createMessageBus('dashboard')
+    const application = connectApplicationToMessageBus(statusHost, {
+      appId: 'favorites',
+    })
+    const responder = vi.fn()
+
+    statusHost.subscribe('applications.status.update', responder)
+    expect(() => application.subscribe('applications.status.update', vi.fn())).toThrowError(
+      expect.objectContaining({code: 'OWNERSHIP_MISMATCH'}),
+    )
+
+    application.emit('applications.status.update', {
+      name: 'list',
+      value: {label: 'Syncing'},
+    })
+    application.emit('applications.status.update', {
+      name: 'list',
+      value: {label: null},
+    })
+
+    expect(responder).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({
+        type: 'applications.status.update',
+        payload: {name: 'list', value: {label: 'Syncing'}},
+        meta: expect.objectContaining({appId: 'favorites'}),
+      }),
+    )
+    expect(responder).toHaveBeenNthCalledWith(
+      2,
+      expect.objectContaining({
+        type: 'applications.status.update',
+        payload: {name: 'list', value: {label: null}},
+        meta: expect.objectContaining({appId: 'favorites'}),
+      }),
+    )
+  })
+
   it('rejects state emits from every connection, including the host', () => {
     const host = createMessageBus('dashboard')
     const panel = {

package/src/dashboard/messageBus/bus.ts

@@ -18,6 +18,7 @@ import {type Application} from '../../applications/applications'
 import {
   DASHBOARD_TOPIC_MANIFEST,
   type EventTopic,
+  type MessageBusTopics,
   type PayloadOf,
   type ReplyOf,
   type StateTopic,
@@ -25,6 +26,7 @@ import {
   type TopicMigration,
   topicMigrations,
   type TopicName,
+  type Topics,
   type ValueOf,
 } from './topics'
 
@@ -78,9 +80,9 @@ export interface MessageBusMeta {
  * A message delivered to an event topic responder.
  * @public
  */
-export interface MessageBusMessage<T, R = never> {
+export interface MessageBusMessage<T, R = never, K extends PropertyKey = TopicName> {
   /** The topic that carries the message. */
-  type: TopicName
+  type: K
   /** The event payload. */
   payload: T
   /** The message provenance. */
@@ -148,39 +150,42 @@ export interface MessageBusEmitResult<R> extends PromiseLike<R> {
  * {@link MessageBusClient.emit}; a connection only ever reads its own values.
  * @public
  */
-export interface MessageBus {
+export interface MessageBus<TTopics = MessageBusTopics> {
   /** Emits an event topic and provides its reply when awaited. */
-  emit<K extends EventTopic>(
+  emit<K extends EventTopic<TTopics>>(
     type: K,
-    ...rest: PayloadOf<K> extends void
+    ...rest: PayloadOf<K, TTopics> extends void
       ? [payload?: void, options?: MessageBusEmitOptions]
-      : [payload: PayloadOf<K>, options?: MessageBusEmitOptions]
-  ): MessageBusEmitResult<ReplyOf<K>>
+      : [payload: PayloadOf<K, TTopics>, options?: MessageBusEmitOptions]
+  ): MessageBusEmitResult<ReplyOf<K, TTopics>>
   /** Reads the current or next value of a state topic. */
-  query<K extends StateTopic>(type: K, options?: MessageBusQueryOptions): Promise<ValueOf<K>>
+  query<K extends StateTopic<TTopics>>(
+    type: K,
+    options?: MessageBusQueryOptions,
+  ): Promise<ValueOf<K, TTopics>>
   /** Runs a responder for each event until its signal aborts. */
-  subscribe<K extends EventTopic>(
+  subscribe<K extends EventTopic<TTopics>>(
     type: K,
-    handler: (message: MessageBusMessage<PayloadOf<K>, ReplyOf<K>>) => void,
+    handler: (message: MessageBusMessage<PayloadOf<K, TTopics>, ReplyOf<K, TTopics>, K>) => void,
     options?: MessageBusAbortOptions,
   ): void
   /** Runs a handler for each state value until its signal aborts. */
-  subscribe<K extends StateTopic>(
+  subscribe<K extends StateTopic<TTopics>>(
     type: K,
-    handler: (value: ValueOf<K>) => void,
+    handler: (value: ValueOf<K, TTopics>) => void,
     options?: MessageBusAbortOptions,
   ): void
   /** Returns a state topic as a `MessageBusStateSource`. */
-  subscribe<K extends StateTopic>(type: K): MessageBusStateSource<ValueOf<K>>
+  subscribe<K extends StateTopic<TTopics>>(type: K): MessageBusStateSource<ValueOf<K, TTopics>>
   /** Returns an event topic as an observable of its payloads. */
-  subscribe<K extends EventTopic>(type: K): Observable<PayloadOf<K>>
+  subscribe<K extends EventTopic<TTopics>>(type: K): Observable<PayloadOf<K, TTopics>>
 }
 
 /**
  * A message bus connection that can be torn down independently of its siblings.
  * @public
  */
-export interface MessageBusConnection extends MessageBus {
+export interface MessageBusConnection<TTopics = MessageBusTopics> extends MessageBus<TTopics> {
   /**
    * Tears down this connection: pending requests reject `ABORTED`, subscriptions
    * complete, and later `emit`, `query`, and `subscribe` calls fail with `ABORTED`.
@@ -214,7 +219,7 @@ export interface MessageBusClient {
  * a snapshot to each new client.
  * @public
  */
-export interface MessageBusHost extends MessageBusConnection {
+export interface MessageBusHost<TTopics = MessageBusTopics> extends MessageBusConnection<TTopics> {
   /**
    * Every open connection other than this one first, then each new one as it joins. The same
    * {@link MessageBusClient} object is handed out for a connection across subscriptions, so it
@@ -641,7 +646,7 @@ export function createIsolatedMessageBus(
   config: {
     migrations?: ReadonlyMap<string, readonly TopicMigration[]>
   } = {},
-): MessageBusHost {
+): MessageBusHost<Topics> {
   if (!appId) throwMissingAppId()
 
   const registry: MessageBusRegistry = {
@@ -658,7 +663,10 @@ export function createIsolatedMessageBus(
 
   mergeTopicManifest(registry, DASHBOARD_TOPIC_MANIFEST)
 
-  return createConnection(registry, {appId, migrations: config.migrations}) as MessageBusHost
+  return createConnection(registry, {
+    appId,
+    migrations: config.migrations,
+  }) as MessageBusHost<Topics>
 }
 
 type TopicVersionAdapter = {
@@ -863,7 +871,7 @@ export interface ConnectApplicationToMessageBusOptions {
 export function connectApplicationToMessageBus(
   installedMessageBus: MessageBus,
   config: ConnectApplicationToMessageBusOptions,
-): MessageBusConnection {
+): MessageBusConnection<Topics> {
   if (!config.appId) throwMissingAppId()
 
   const {appId} = config
@@ -902,7 +910,7 @@ export function connectApplicationToMessageBus(
     return createRejectedConnection(() => error)
   }
 
-  return createConnection(registry, config)
+  return createConnection(registry, config) as MessageBusConnection<Topics>
 }
 
 // Hands the host the same client object for a connection across `connections` subscriptions.
@@ -1202,7 +1210,7 @@ export interface InstallMessageBusOptions {
  * connection it would get has no `connections`.
  * @internal
  */
-export function installMessageBus(options: InstallMessageBusOptions = {}): MessageBusHost {
+export function installMessageBus(options: InstallMessageBusOptions = {}): MessageBusHost<Topics> {
   const appId = resolveAppId(options.appId) ?? throwMissingAppId()
   const installedMessageBus = getInstalledMessageBus()
   if (installedMessageBus) {
@@ -1214,7 +1222,9 @@ export function installMessageBus(options: InstallMessageBusOptions = {}): Messa
         `Cannot install the message bus as "${appId}": it is already installed by "${installedAppId}". Applications connect with connectMessageBus().`,
       )
     }
-    return connectApplicationToMessageBus(installedMessageBus, {appId}) as MessageBusHost
+    return connectApplicationToMessageBus(installedMessageBus, {
+      appId,
+    }) as MessageBusHost<Topics>
   }
 
   const globals = globalThis as {[MESSAGE_BUS_KEY]?: MessageBus}

package/src/dashboard/messageBus/topics.test.ts

@@ -1,13 +1,18 @@
-import {describe, expectTypeOf, it} from 'vitest'
+import {describe, expect, expectTypeOf, it} from 'vitest'
 
 import {type Application, type ApplicationInclude} from '../../applications/applications'
 import {type MessageBus} from './bus'
 import {
   type ApplicationConfig,
   type ApplicationConfigAppType,
+  type ApplicationStatusUpdate,
+  DASHBOARD_TOPIC_MANIFEST,
+  type DashboardTopics,
+  type EventTopic,
   type PayloadOf,
   type ReplyOf,
   type StateTopic,
+  type TopicName,
   type TopicResult,
   type ValueOf,
 } from './topics'
@@ -28,7 +33,26 @@ describe('dashboard topic types', () => {
     expectTypeOf<Parameters<MessageBus['query']>[0]>().toEqualTypeOf<StateTopic>()
   })
 
+  it('keeps application status internal', () => {
+    expectTypeOf<ApplicationStatusUpdate>().toEqualTypeOf<{
+      name: string
+      value: {label: string | null}
+    }>()
+    expect(DASHBOARD_TOPIC_MANIFEST['applications.status.update']).toEqual({
+      kind: 'event',
+      ownership: {type: 'same_app'},
+    })
+    expectTypeOf<'applications.status.update'>().toMatchTypeOf<TopicName>()
+    expectTypeOf<'applications.status.update'>().not.toMatchTypeOf<EventTopic>()
+    expectTypeOf<PayloadOf<'applications.status.update'>>().toEqualTypeOf<ApplicationStatusUpdate>()
+    expectTypeOf<ReplyOf<'applications.status.update'>>().toBeNever()
+  })
+
   it('exposes application state values', () => {
+    expectTypeOf<ValueOf<'applications.base-path'>>().toEqualTypeOf<TopicResult<string>>()
+    expectTypeOf<ValueOf<'applications.foreground', DashboardTopics>>().toEqualTypeOf<
+      Application['id'] | null
+    >()
     expectTypeOf<ValueOf<'applications.config'>>().toEqualTypeOf<ApplicationConfig[] | null>()
     expectTypeOf<ValueOf<'applications.list'>>().toEqualTypeOf<TopicResult<
       Application<ApplicationInclude>[]
@@ -60,12 +84,22 @@ describe('dashboard topic types', () => {
   })
 
   it('requires payloads only for events that declare one', () => {
-    const messageBus = {emit: () => undefined} as unknown as MessageBus
+    const messageBus = {
+      emit: () => undefined,
+      query: () => undefined,
+      subscribe: () => undefined,
+    } as unknown as MessageBus
 
     messageBus.emit('auth.token.refresh')
     messageBus.emit('auth.token.refresh', undefined, {timeout: null})
     messageBus.emit('navigation.location.update', {url: '/'})
     // @ts-expect-error navigation.location.update requires a payload
     messageBus.emit('navigation.location.update')
+    // @ts-expect-error applications.status.update is internal
+    messageBus.emit('applications.status.update', {name: 'media', value: {label: null}})
+    // @ts-expect-error applications.status.update is internal
+    messageBus.subscribe('applications.status.update')
+    // @ts-expect-error applications.status.update is internal
+    messageBus.subscribe('applications.status.update', () => {})
   })
 })