@mdjhnson/homebridge-yoto 0.1.5 → 0.1.7

package/README.md

@@ -2,7 +2,7 @@
 
 <img src="https://github.com/homebridge/branding/raw/latest/logos/homebridge-wordmark-logo-vertical.png" width="150">
 
-<img src="https://raw.githubusercontent.com/mdjhnson/homebridge-yoto/master/logo.png" width="150">
+<img src="https://raw.githubusercontent.com/mdjhnson/homebridge-yoto/master/homebridge-ui/public/logo.png" width="100">
 
 </p>
 
@@ -46,7 +46,7 @@ Using your own Yoto developer app? Make it a **Public Client**, add `http://127.
 
 The plugin asks for access to view, configure and control your players, plus read-only access to your card library (used to name shortcut switches and to list your cards as TV inputs). If you signed in with an older version, sign in again so the new permissions apply.
 
-The plugin refreshes its tokens on its own. If the login ever expires or is revoked, the Homebridge log will say so. Sign in again from the plugin settings.
+The plugin refreshes its tokens on its own, about once a day, and logs each refresh. If the login ever expires or is revoked, the plugin settings show **Yoto login expired** and the Home app shows the players as **Not Responding**. Sign in again from the plugin settings, then restart the child bridge.
 
 ## Settings
 

package/config.schema.json

@@ -8,11 +8,16 @@
   "schema": {
     "type": "object",
     "properties": {
+      "name": {
+        "title": "Name",
+        "type": "string",
+        "default": "Yoto",
+        "description": "Name used for this plugin in the Homebridge log."
+      },
       "clientId": {
         "title": "OAuth Client ID",
         "type": "string",
         "default": "tpc_ot5BY24FLyZoCX9MnykipB",
-        "required": false,
         "description": "OAuth client ID for Yoto API authentication. The default works for most users. Only change if you've created your own OAuth app at yoto.dev.",
         "x-schema-form": {
           "hidden": false
@@ -21,7 +26,6 @@
       "accessToken": {
         "title": "Access Token",
         "type": "string",
-        "required": false,
         "description": "Automatically managed by the authentication flow. Do not edit manually.",
         "x-schema-form": {
           "type": "password"
@@ -30,7 +34,6 @@
       "refreshToken": {
         "title": "Refresh Token",
         "type": "string",
-        "required": false,
         "description": "Automatically managed by the authentication flow. Do not edit manually.",
         "x-schema-form": {
           "type": "password"
@@ -39,7 +42,6 @@
       "tokenExpiresAt": {
         "title": "Token Expiration",
         "type": "number",
-        "required": false,
         "description": "Automatically managed by the authentication flow. Do not edit manually.",
         "x-schema-form": {
           "hidden": true
@@ -50,7 +52,6 @@
         "type": "integer",
         "default": 60000,
         "minimum": 10000,
-        "required": false,
         "description": "How often to poll the Yoto API for device status and config as a fallback to MQTT updates. Defaults to 60000 (1 minute)."
       },
       "services": {
@@ -116,13 +117,11 @@
                 "label": {
                   "title": "Label",
                   "type": "string",
-                  "required": true,
                   "description": "Name shown in HomeKit for this card control."
                 },
                 "cardId": {
                   "title": "Card ID",
                   "type": "string",
-                  "required": true,
                   "description": "The Yoto card ID to play."
                 },
                 "playOnAll": {
@@ -131,7 +130,11 @@
                   "default": false,
                   "description": "Create a separate accessory that plays this card on every Yoto."
                 }
-              }
+              },
+              "required": [
+                "label",
+                "cardId"
+              ]
             }
           },
           "shortcuts": {
@@ -250,6 +253,7 @@
       "expandable": true,
       "expanded": false,
       "items": [
+        "name",
         "httpPollIntervalMs",
         {
           "type": "help",

package/homebridge-ui/public/client.js

@@ -5,7 +5,7 @@
  */
 
 /** @import {IHomebridgePluginUi} from '@homebridge/plugin-ui-utils/ui.interface' */
-/** @import { AuthConfigResponse, AuthStartResponse, AuthExchangeResponse } from '../server.js' */
+/** @import { AuthConfigResponse, AuthStartResponse, AuthExchangeResponse, AuthStatusResponse } from '../server.js' */
 
 /**
  * @global
@@ -16,6 +16,7 @@ const homebridge = window.homebridge
 /**
  * @typedef {Object} YotoConfig
  * @property {string} [platform] - Platform alias (always "Yoto")
+ * @property {string} [name] - Name used in the Homebridge log
  * @property {string} [clientId] - OAuth client ID (only stored when not the default)
  * @property {string} [refreshToken] - Stored refresh token
  * @property {string} [accessToken] - Stored access token
@@ -31,6 +32,8 @@ let authorizeUrl = null
 let pluginConfig = []
 /** @type {string | null} */
 let defaultClientId = null
+/** @type {string | null} */
+let defaultName = null
 /** @type {string[]} */
 let legacyClientIds = []
 
@@ -52,6 +55,7 @@ async function initializeUI () {
   document.getElementById('cancelAuthButton')?.addEventListener('click', showAuthRequired)
   document.getElementById('retryButton')?.addEventListener('click', showAuthRequired)
   document.getElementById('logoutButton')?.addEventListener('click', logout)
+  document.getElementById('reauthButton')?.addEventListener('click', startAuthorization)
   getInput('callbackInput')?.addEventListener('keydown', (event) => {
     if (event.key === 'Enter') finishAuthorization()
   })
@@ -60,7 +64,7 @@ async function initializeUI () {
 
   // Load auth config and check authentication status
   await loadAuthConfig()
-  checkAuthStatus()
+  await checkAuthStatus()
 }
 
 // Initialize on ready
@@ -78,6 +82,7 @@ function showSection (sectionToShow, options = {}) {
     'authRequired',
     'authCodeSection',
     'authSuccess',
+    'authExpired',
     'errorSection'
   ]
 
@@ -153,14 +158,13 @@ function getErrorMessage (error, fallback) {
 async function loadAuthConfig () {
   try {
     pluginConfig = await homebridge.getPluginConfig()
-    if (!pluginConfig.length) {
-      pluginConfig.push({ platform: 'Yoto' })
-    }
 
     /** @type {AuthConfigResponse} */
     const config = await homebridge.request('/auth/config')
     defaultClientId = config.defaultClientId
+    defaultName = config.defaultName
     legacyClientIds = config.legacyClientIds
+    getPlatformBlock()
 
     const redirectUriDisplay = document.getElementById('redirectUriDisplay')
     if (redirectUriDisplay) redirectUriDisplay.textContent = config.redirectUri
@@ -178,6 +182,18 @@ async function loadAuthConfig () {
   }
 }
 
+/**
+ * The plugin's config block, created if missing. Also fills in the name,
+ * which blocks saved by older versions don't have.
+ * @returns {YotoConfig}
+ */
+function getPlatformBlock () {
+  if (!pluginConfig[0]) pluginConfig[0] = { platform: 'Yoto' }
+  const config = pluginConfig[0]
+  if (!config.name && defaultName) config.name = defaultName
+  return config
+}
+
 /**
  * The client ID saved in config, ignoring retired ones
  * @returns {string | undefined}
@@ -265,19 +281,15 @@ async function finishAuthorization () {
       response: pasted,
     })
 
-    if (!pluginConfig[0]) pluginConfig[0] = { platform: 'Yoto' }
-    const config = pluginConfig[0]
+    const config = getPlatformBlock()
     config.refreshToken = result.refreshToken
     config.accessToken = result.accessToken
     config.tokenExpiresAt = result.tokenExpiresAt
 
-    // Only store a client ID when it differs from the default, so future
-    // default changes apply automatically.
-    if (result.clientId && result.clientId !== defaultClientId) {
-      config.clientId = result.clientId
-    } else {
-      delete config.clientId
-    }
+    // Always set the client ID. Deleting it isn't enough: the settings form
+    // keeps the value it loaded (e.g. a retired client ID) and saves it back.
+    // If the default ever changes, add the old one to LEGACY_CLIENT_IDS.
+    config.clientId = result.clientId
 
     await homebridge.updatePluginConfig(pluginConfig)
     await homebridge.savePluginConfig()
@@ -306,11 +318,12 @@ async function logout () {
   try {
     homebridge.showSpinner()
 
-    if (pluginConfig[0]) {
-      delete pluginConfig[0].refreshToken
-      delete pluginConfig[0].accessToken
-      delete pluginConfig[0].tokenExpiresAt
-    }
+    // Blank the tokens rather than deleting them: the settings form keeps
+    // values the client deletes and would save the old login back
+    const config = getPlatformBlock()
+    config.refreshToken = ''
+    config.accessToken = ''
+    delete config.tokenExpiresAt
 
     await homebridge.updatePluginConfig(pluginConfig)
     await homebridge.savePluginConfig()
@@ -327,13 +340,32 @@ async function logout () {
 }
 
 /**
- * Check initial authentication status
+ * Check initial authentication status. Saved tokens aren't proof of a working
+ * login, so ask whether the plugin found that Yoto rejected them.
+ * @returns {Promise<void>}
  */
-function checkAuthStatus () {
+async function checkAuthStatus () {
   const config = pluginConfig[0]
-  if (config?.refreshToken && config?.accessToken) {
-    showSection('authSuccess')
-  } else {
+  if (!config?.refreshToken || !config?.accessToken) {
     showAuthRequired()
+    return
+  }
+
+  try {
+    /** @type {AuthStatusResponse} */
+    const status = await homebridge.request('/auth/status', { refreshToken: config.refreshToken })
+    if (status.expired) {
+      const detail = document.getElementById('authExpiredMessage')
+      if (detail) {
+        const when = status.at ? new Date(status.at).toLocaleString() : ''
+        detail.textContent = [when && `Since ${when}.`, status.message].filter(Boolean).join(' ')
+      }
+      showSection('authExpired')
+      return
+    }
+  } catch (error) {
+    // Older Homebridge UI versions or a read error: fall back to the saved tokens
+    console.error('Failed to check the login status:', error)
   }
+  showSection('authSuccess')
 }

package/homebridge-ui/public/index.html

@@ -2,6 +2,8 @@
 <script type="module" src="client.js"></script>
 
 <div class="card card-body">
+  <img src="logo.png" alt="Homebridge Yoto" width="80" height="80" class="d-block mx-auto mb-3" />
+
   <!-- Authentication Status -->
   <div id="authStatus">
     <h4>Authentication Status</h4>
@@ -112,6 +114,23 @@
     </div>
   </div>
 
+  <!-- Login Expired -->
+  <div id="authExpired" style="display: none">
+    <div class="alert alert-danger">
+      <h5>Yoto login expired</h5>
+      <p>
+        Yoto no longer accepts the saved login, so your players can't be
+        controlled from HomeKit. Sign in again, then restart the child bridge.
+      </p>
+      <p class="small mb-0" id="authExpiredMessage"></p>
+    </div>
+    <div class="text-center">
+      <button id="reauthButton" type="button" class="btn btn-primary btn-lg">
+        Sign in again
+      </button>
+    </div>
+  </div>
+
   <!-- Error Display -->
   <div id="errorSection" style="display: none">
     <div class="alert alert-danger">

package/homebridge-ui/server.js

@@ -11,11 +11,13 @@ import { HomebridgePluginUiServer, RequestError } from '@homebridge/plugin-ui-ut
 import { YotoClient } from 'yoto-nodejs-client'
 import {
   DEFAULT_CLIENT_ID,
+  DEFAULT_NAME,
   LEGACY_CLIENT_IDS,
   OAUTH_REDIRECT_URI,
   OAUTH_SCOPES,
 } from '../lib/settings.js'
 import { createOAuthState, createPkcePair, parseAuthorizationResponse } from '../lib/utils/oauth.js'
+import { readLoginProblem } from '../lib/utils/login-status.js'
 
 const AUDIENCE = 'https://api.yotoplay.com'
 /** Sign-in attempts are discarded after this long */
@@ -46,6 +48,7 @@ class YotoUiServer extends HomebridgePluginUiServer {
     this.onRequest('/auth/config', getAuthConfig)
     this.onRequest('/auth/start', startAuthorization)
     this.onRequest('/auth/exchange', exchangeAuthorizationCode)
+    this.onRequest('/auth/status', (/** @type {AuthStatusRequest} */ payload) => getLoginStatus(this.homebridgeStoragePath, payload))
 
     // this MUST be called when you are ready to accept requests
     this.ready()
@@ -59,6 +62,7 @@ class YotoUiServer extends HomebridgePluginUiServer {
  * Response from /auth/config endpoint
  * @typedef {Object} AuthConfigResponse
  * @property {string} defaultClientId - The default OAuth client ID
+ * @property {string} defaultName - The default plugin name, filled into config blocks that have none
  * @property {string[]} legacyClientIds - Client IDs that no longer support sign-in
  * @property {string} redirectUri - Redirect URI to register on a custom Yoto app
  */
@@ -70,11 +74,40 @@ class YotoUiServer extends HomebridgePluginUiServer {
 async function getAuthConfig () {
   return {
     defaultClientId: DEFAULT_CLIENT_ID,
+    defaultName: DEFAULT_NAME,
     legacyClientIds: LEGACY_CLIENT_IDS,
     redirectUri: OAUTH_REDIRECT_URI,
   }
 }
 
+/**
+ * Request payload for /auth/status endpoint
+ * @typedef {Object} AuthStatusRequest
+ * @property {string} [refreshToken] - Refresh token in the settings being shown
+ */
+
+/**
+ * Response from /auth/status endpoint
+ * @typedef {Object} AuthStatusResponse
+ * @property {boolean} expired - True when the plugin found this login no longer works
+ * @property {string} [message] - What went wrong
+ * @property {string} [at] - When it happened (ISO 8601)
+ */
+
+/**
+ * Whether the plugin recorded that the saved login stopped working. The plugin
+ * records the refresh token's fingerprint, so a login replaced by signing in
+ * again isn't reported.
+ * @param {string | undefined} storagePath - Homebridge storage folder
+ * @param {AuthStatusRequest} payload
+ * @returns {Promise<AuthStatusResponse>}
+ */
+async function getLoginStatus (storagePath, payload) {
+  if (!storagePath) return { expired: false }
+  const problem = await readLoginProblem(storagePath, payload?.refreshToken)
+  return problem ? { expired: true, message: problem.message, at: problem.at } : { expired: false }
+}
+
 /**
  * Request payload for /auth/start endpoint
  * @typedef {Object} AuthStartRequest

package/lib/platform.js

@@ -9,6 +9,7 @@
 /** @import { PlaybackAccessoryConfig } from './service-config.js' */
 /** @import { CardControlConfig } from './card-controls.js' */
 /** @import { LibraryCard } from './utils/library.js' */
+/** @import { RefreshSuccessEvent } from 'yoto-nodejs-client/lib/token.js' */
 
 /**
  * Context stored in PlatformAccessory for Yoto devices
@@ -47,6 +48,8 @@ import { applyTokenUpdate, findNewerSavedTokens } from './utils/token-config.js'
 import { tolerateMissingStatusScope } from './utils/status-scope-fallback.js'
 import { getTokenClientId } from './utils/token-client-id.js'
 import { fetchFamilyLibrary } from './utils/library.js'
+import { clearLoginProblem, writeLoginProblem } from './utils/login-status.js'
+import { markAccessoryUnreachable } from './utils/unreachable.js'
 
 /** First retry delay when the Yoto API can't be reached at startup; doubles each attempt */
 const START_RETRY_BASE_MS = 30 * 1000
@@ -94,6 +97,8 @@ export class YotoPlatform {
   /** @type {Map<string, Promise<string | null>>} */ cardTitleCache = new Map()
   /** @type {{ fetchedAt: number, cards: Promise<LibraryCard[]> } | null} */ libraryCache = null
   /** @type {boolean} */ authInvalid = false
+  /** @type {boolean} */ launched = false
+  /** @type {boolean} */ markOnLaunch = false
   /** @type {number} */ startRetryCount = 0
   /** @type {ReturnType<typeof setTimeout> | null} */ startRetryTimer = null
   /** @type {boolean} */ shuttingDown = false
@@ -138,13 +143,14 @@ export class YotoPlatform {
     // Check if we have authentication tokens
     if (!refreshToken || !accessToken) {
       log.warn('No authentication tokens found. Please configure the plugin through the Homebridge UI.')
+      // Cached accessories would otherwise show their last state and ignore taps
+      this.markAccessoriesUnreachable()
       return
     }
 
     log.debug('Authentication tokens found, initializing Yoto account...')
 
     const { sessionId } = this
-    const updateHomebridgeConfig = this.updateHomebridgeConfig.bind(this)
 
     // Initialize YotoAccount with client and device options. It decodes the saved
     // access token, which throws if config.json holds a malformed one; Homebridge
@@ -157,38 +163,21 @@ export class YotoPlatform {
           clientId,
           refreshToken,
           accessToken,
-          onTokenRefresh: async ({ updatedAccessToken, updatedRefreshToken, updatedExpiresAt, prevAccessToken, prevRefreshToken }) => {
-            // Client reports expiry in seconds; config.json stores milliseconds (matches the UI)
-            const tokenExpiresAt = updatedExpiresAt * 1000
-            log.debug('Access token refreshed, expires at:', new Date(tokenExpiresAt).toISOString())
-
-            // Keep the in-memory config in sync so later reads see current tokens
-            config['accessToken'] = updatedAccessToken
-            config['refreshToken'] = updatedRefreshToken
-            config['tokenExpiresAt'] = tokenExpiresAt
-
-            await updateHomebridgeConfig((configContents) => applyTokenUpdate(configContents, {
-              platform: PLATFORM_NAME,
-              accessToken: updatedAccessToken,
-              refreshToken: updatedRefreshToken,
-              tokenExpiresAt,
-              prevAccessToken,
-              prevRefreshToken,
-            }))
-          },
+          onTokenRefresh: (event) => this.saveRefreshedTokens(event),
           onRefreshStart: () => {
-            log.debug('Refreshing Yoto access token...')
+            // Logged at info, so a refresh cut short (e.g. by a restart) shows in the log
+            log.info('Refreshing the Yoto login...')
           },
           onRefreshError: (error) => {
             log.warn('Yoto token refresh failed, will retry:', error.message)
             log.debug('Token refresh error details:', formatError(error))
           },
           onInvalid: (error) => {
-            this.authInvalid = true
             log.error(
               'Yoto login has expired or been revoked. Open the plugin settings in the Homebridge UI and sign in again.',
               error.message
             )
+            this.handleLoginProblem(`Yoto rejected the saved login: ${error.message}`)
           },
         },
         deviceOptions: {
@@ -203,6 +192,7 @@ export class YotoPlatform {
         'Could not load the saved Yoto login. Open the plugin settings in the Homebridge UI and sign in again.',
         errorMessage(error)
       )
+      this.handleLoginProblem(`The saved login could not be read: ${errorMessage(error)}`)
       return
     }
     this.yotoAccount = account
@@ -235,6 +225,7 @@ export class YotoPlatform {
     // to start discovery of new accessories.
     api.on('didFinishLaunching', async () => {
       log.debug('Executed didFinishLaunching callback')
+      this.launched = true
       // Start the YotoAccount which will discover and start all devices
       await this.startAccount()
     })
@@ -304,8 +295,9 @@ export class YotoPlatform {
       listeners.on('deviceAdded', async ({ deviceId }) => {
         // The account doesn't await this listener, so errors must not escape it
         try {
-          // Homebridge may shut down while the account is still starting
-          if (this.shuttingDown || !this.yotoAccount) return
+          // Homebridge may shut down while the account is still starting. With a dead
+          // login, a new handler would bring back tiles that show stale state.
+          if (this.shuttingDown || this.authInvalid || !this.yotoAccount) return
           const deviceModel = this.yotoAccount.getDevice(deviceId)
           if (!deviceModel) {
             const label = this.formatDeviceLabel(deviceId)
@@ -469,6 +461,7 @@ export class YotoPlatform {
           `Yoto rejected the saved login (HTTP ${statusCode}). Open the plugin settings in the Homebridge UI and sign in again.`,
           formatError(error)
         )
+        this.handleLoginProblem(`Yoto rejected the saved login (HTTP ${statusCode}): ${errorMessage(error)}`)
         return
       }
       if (!isRetryableStartError(error)) {
@@ -495,7 +488,22 @@ export class YotoPlatform {
     }
 
     this.startRetryCount = 0
+
+    // YotoAccount.start() swallows device start errors, so the login can be
+    // rejected during a start that still resolves
+    if (this.authInvalid) {
+      await account.stop()
+      this.markAccessoriesUnreachable()
+      return
+    }
+
     this.log.info(`✓ Yoto account started with ${account.devices.size} device(s)`)
+    const storagePath = this.getStoragePath()
+    if (storagePath) {
+      clearLoginProblem(storagePath, this.config['refreshToken']).catch(error => {
+        this.log.debug('Could not clear the recorded login problem:', errorMessage(error))
+      })
+    }
     this.log.debug(
       'Account devices:',
       Array.from(account.devices.keys()).join(', ') || 'none'
@@ -1144,6 +1152,99 @@ export class YotoPlatform {
     this.log.debug('✓ Yoto platform shutdown complete')
   }
 
+  /**
+   * Save tokens the client just refreshed. Yoto's refresh tokens are single-use,
+   * so a refreshed login that isn't saved is lost on the next restart.
+   * @param {RefreshSuccessEvent} event
+   * @returns {Promise<void>}
+   */
+  async saveRefreshedTokens ({ clientId, updatedAccessToken, updatedRefreshToken, updatedExpiresAt, prevAccessToken, prevRefreshToken }) {
+    // Client reports expiry in seconds; config.json stores milliseconds (matches the UI)
+    const tokenExpiresAt = updatedExpiresAt * 1000
+    this.log.debug('Access token refreshed, expires at:', new Date(tokenExpiresAt).toISOString())
+
+    // Keep the in-memory config in sync so later reads see current tokens
+    this.config['accessToken'] = updatedAccessToken
+    this.config['refreshToken'] = updatedRefreshToken
+    this.config['tokenExpiresAt'] = tokenExpiresAt
+
+    const saved = await this.updateHomebridgeConfig((configContents) => applyTokenUpdate(configContents, {
+      platform: PLATFORM_NAME,
+      accessToken: updatedAccessToken,
+      refreshToken: updatedRefreshToken,
+      tokenExpiresAt,
+      prevAccessToken,
+      prevRefreshToken,
+      clientId,
+    }))
+    if (saved) {
+      this.log.info(`Refreshed the Yoto login and saved it to config.json. It's valid until ${new Date(tokenExpiresAt).toLocaleString()} and is refreshed shortly before then.`)
+    }
+  }
+
+  /**
+   * The saved Yoto login no longer works. Record it for the settings UI, and make
+   * the accessories show "Not Responding" instead of their last known state.
+   * @param {string} message - What went wrong, shown in the settings UI
+   */
+  handleLoginProblem (message) {
+    this.authInvalid = true
+    this.markAccessoriesUnreachable()
+    // Stop polling and MQTT: every call would fail until a restart, and pushed
+    // updates would refresh tiles that should read Not Responding
+    this.yotoAccount?.stop().catch(error => {
+      this.log.debug('Could not stop the Yoto account:', errorMessage(error))
+    })
+
+    const storagePath = this.getStoragePath()
+    if (!storagePath) return
+    writeLoginProblem(storagePath, { message, refreshToken: this.config['refreshToken'] }).catch(error => {
+      this.log.debug('Could not record the login problem for the settings UI:', errorMessage(error))
+    })
+  }
+
+  /**
+   * Show every accessory this platform knows of as "Not Responding" in HomeKit.
+   * Cached accessories are only known once Homebridge has finished launching,
+   * so before then this waits for it.
+   */
+  markAccessoriesUnreachable () {
+    if (!this.launched) {
+      if (!this.markOnLaunch) {
+        this.markOnLaunch = true
+        this.api.on('didFinishLaunching', () => {
+          this.launched = true
+          this.markAccessoriesUnreachable()
+        })
+      }
+      return
+    }
+
+    const accessories = [
+      ...this.accessories.values(),
+      ...this.cardAccessories.values(),
+      ...this.speakerAccessories.values(),
+      ...this.televisionAccessories.values(),
+    ]
+    if (!accessories.length) return
+    for (const accessory of accessories) {
+      markAccessoryUnreachable(accessory, this.api.hap)
+    }
+    this.log.warn(`The Home app will show ${accessories.length} Yoto accessory(s) as Not Responding until you sign in again and restart the child bridge.`)
+  }
+
+  /**
+   * Homebridge's storage folder, or null if it isn't known
+   * @returns {string | null}
+   */
+  getStoragePath () {
+    try {
+      return this.api.user.storagePath()
+    } catch {
+      return null
+    }
+  }
+
   /**
    * Replace the tokens in `config` with newer ones saved in config.json, if any.
    * @param {PlatformConfig} config
@@ -1171,6 +1272,7 @@ export class YotoPlatform {
   /**
    * Update Homebridge config.json file
    * @param {(configContents: string) => string | null} updateFn - Returns updated contents, or null if it could not apply the update
+   * @returns {Promise<boolean>} Whether config.json was updated
    */
   async updateHomebridgeConfig (updateFn) {
     const configPath = this.api.user.configPath()
@@ -1180,7 +1282,7 @@ export class YotoPlatform {
       const updatedContents = updateFn(configContents)
       if (updatedContents === null) {
         this.log.warn(`Did not save refreshed tokens: no ${PLATFORM_NAME} platform block in ${configPath} holds the current tokens. If you signed in again or logged out in the plugin settings, restart Homebridge to use the new settings.`)
-        return
+        return false
       }
       // Write to a temp file and rename so a crash mid-write cannot corrupt config.json.
       // Keep the original file mode, since config.json holds tokens.
@@ -1202,8 +1304,10 @@ export class YotoPlatform {
         await writeFile(configPath, updatedContents, 'utf8')
       }
       this.log.debug('Updated config.json with new tokens')
+      return true
     } catch (error) {
       this.log.error(`Failed to update config.json at ${configPath}. Refreshed tokens may not persist:`, errorMessage(error))
+      return false
     }
   }
 }

package/lib/settings.js

@@ -15,6 +15,11 @@ export const PLUGIN_NAME = '@mdjhnson/homebridge-yoto'
  */
 export const DEFAULT_CLIENT_ID = configSchema.schema.properties.clientId.default
 
+/**
+ * Default plugin name (shown in the Homebridge log) from config schema
+ */
+export const DEFAULT_NAME = configSchema.schema.properties.name.default
+
 /**
  * OAuth redirect URI registered on the Yoto developer app. Nothing listens here:
  * the user copies the resulting address back into the plugin settings.

package/lib/utils/login-status.js

@@ -0,0 +1,99 @@
+/**
+ * @fileoverview Records a Yoto login that stopped working, so the settings UI can
+ * say so. The plugin runs in a child bridge and the settings UI in the Homebridge
+ * UI process, so they share this small file in the Homebridge storage folder.
+ */
+
+import { createHash } from 'node:crypto'
+import { readFile, rename, unlink, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+export const LOGIN_STATUS_FILE = 'yoto-login-status.json'
+
+/**
+ * @typedef {Object} LoginProblem
+ * @property {string} message - What went wrong, for the settings UI
+ * @property {string} at - When it happened (ISO 8601)
+ * @property {string | null} tokenFingerprint - Fingerprint of the refresh token that failed
+ */
+
+/**
+ * A short, one-way fingerprint of a refresh token. It tells which login a
+ * problem belongs to without storing the token.
+ * @param {unknown} refreshToken
+ * @returns {string | null}
+ */
+export function tokenFingerprint (refreshToken) {
+  if (typeof refreshToken !== 'string' || !refreshToken) return null
+  return createHash('sha256').update(refreshToken).digest('hex').slice(0, 16)
+}
+
+/**
+ * @param {string} storagePath - Homebridge storage folder
+ * @returns {string}
+ */
+export function loginStatusPath (storagePath) {
+  return join(storagePath, LOGIN_STATUS_FILE)
+}
+
+/**
+ * Record that the login holding `refreshToken` no longer works.
+ * @param {string} storagePath
+ * @param {{ message: string, refreshToken: unknown, now?: Date }} problem
+ * @returns {Promise<void>}
+ */
+export async function writeLoginProblem (storagePath, { message, refreshToken, now = new Date() }) {
+  /** @type {LoginProblem} */
+  const record = { message, at: now.toISOString(), tokenFingerprint: tokenFingerprint(refreshToken) }
+  const path = loginStatusPath(storagePath)
+  const tmpPath = `${path}.${process.pid}.tmp`
+  try {
+    await writeFile(tmpPath, `${JSON.stringify(record, null, 2)}\n`, 'utf8')
+    await rename(tmpPath, path)
+  } catch (error) {
+    await unlink(tmpPath).catch(() => {})
+    throw error
+  }
+}
+
+/**
+ * Remove the problem recorded for the login holding `refreshToken`, once that
+ * login works after all. A problem recorded for another login (e.g. another
+ * Yoto platform block) is kept.
+ * @param {string} storagePath
+ * @param {unknown} refreshToken
+ * @returns {Promise<void>}
+ */
+export async function clearLoginProblem (storagePath, refreshToken) {
+  if (!await readLoginProblem(storagePath, refreshToken)) return
+  try {
+    await unlink(loginStatusPath(storagePath))
+  } catch (error) {
+    if (/** @type {NodeJS.ErrnoException} */ (error).code !== 'ENOENT') throw error
+  }
+}
+
+/**
+ * The recorded problem for the login holding `refreshToken`, if any. A problem
+ * recorded for another login (e.g. one replaced by signing in again) is ignored.
+ * @param {string} storagePath
+ * @param {unknown} refreshToken
+ * @returns {Promise<LoginProblem | null>}
+ */
+export async function readLoginProblem (storagePath, refreshToken) {
+  const fingerprint = tokenFingerprint(refreshToken)
+  if (!fingerprint) return null
+
+  /** @type {unknown} */
+  let parsed
+  try {
+    parsed = JSON.parse(await readFile(loginStatusPath(storagePath), 'utf8'))
+  } catch {
+    return null
+  }
+  if (!parsed || typeof parsed !== 'object') return null
+  const record = /** @type {Record<string, unknown>} */ (parsed)
+  if (record['tokenFingerprint'] !== fingerprint) return null
+  if (typeof record['message'] !== 'string' || typeof record['at'] !== 'string') return null
+  return { message: record['message'], at: record['at'], tokenFingerprint: fingerprint }
+}

package/lib/utils/token-config.js

@@ -6,6 +6,7 @@
  * @property {number} tokenExpiresAt - Expiry as a unix timestamp in milliseconds
  * @property {string} [prevAccessToken] - Previous access token, used to pick the right block
  * @property {string} [prevRefreshToken] - Previous refresh token, used to pick the right block
+ * @property {string} [clientId] - Client ID the tokens were issued to. Replaces a different saved one.
  */
 
 /**
@@ -53,6 +54,11 @@ export function applyTokenUpdate (configContents, update) {
   block['accessToken'] = update.accessToken
   block['refreshToken'] = update.refreshToken
   block['tokenExpiresAt'] = update.tokenExpiresAt
+  // The settings form can save a stale client ID back; keep it matching the tokens.
+  // A missing one means the default, and is left out.
+  if (update.clientId && block['clientId'] !== undefined && block['clientId'] !== update.clientId) {
+    block['clientId'] = update.clientId
+  }
 
   // Homebridge writes config.json with 4-space indentation
   return JSON.stringify(parsed, null, 4)

package/lib/utils/unreachable.js

@@ -0,0 +1,31 @@
+/** @import { API, PlatformAccessory } from 'homebridge' */
+
+/**
+ * Make HomeKit show an accessory as "Not Responding". Every read and write fails
+ * with a communication error, instead of the tiles showing the last known state
+ * and silently ignoring taps.
+ *
+ * This replaces the handlers for good. Nothing needs them back: a new sign-in only
+ * takes effect when the child bridge restarts, which sets them up again.
+ * @param {PlatformAccessory} accessory
+ * @param {API['hap']} hap
+ */
+export function markAccessoryUnreachable (accessory, hap) {
+  const { Service, Characteristic, HapStatusError, HAPStatus, Perms } = hap
+  const skippedServices = new Set([Service.AccessoryInformation.UUID, Service.ProtocolInformation.UUID])
+  // Keep names readable so the Home app still shows which tile is which
+  const skippedCharacteristics = new Set([Characteristic.Name.UUID, Characteristic.ConfiguredName.UUID])
+  const fail = () => {
+    throw new HapStatusError(HAPStatus.SERVICE_COMMUNICATION_FAILURE)
+  }
+
+  for (const service of accessory.services) {
+    if (skippedServices.has(service.UUID)) continue
+    for (const characteristic of service.characteristics) {
+      if (skippedCharacteristics.has(characteristic.UUID)) continue
+      const { perms } = characteristic.props
+      if (perms.includes(Perms.PAIRED_READ)) characteristic.onGet(fail)
+      if (perms.includes(Perms.PAIRED_WRITE)) characteristic.onSet(fail)
+    }
+  }
+}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@mdjhnson/homebridge-yoto",
   "displayName": "Homebridge Yoto",
   "description": "Control your Yoto players through Apple HomeKit with real-time MQTT updates",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "author": "mdjhnson (https://github.com/mdjhnson)",
   "contributors": [
     "Bret Comnes <bcomnes@gmail.com> (https://bret.io)"
@@ -22,6 +22,7 @@
   "devDependencies": {
     "@types/node": "^25.9.8",
     "@voxpelli/tsconfig": "^16.2.1",
+    "ajv": "^8.20.0",
     "auto-changelog": "^2.0.0",
     "c8": "^10.0.0",
     "eslint": "^9.39.2",