@mosaic-home/capacitor-home-assistant

A Capacitor plugin for Home Assistant apps on Android: Home Assistant's own login page in a native WebView, token storage encrypted with an Android Keystore key, finding Home Assistant on the network over mDNS, and native HTTP for REST calls. Native code (widgets, background work) gets a small REST client, HaRest, that reads the same tokens.

Part of the Mosaic Home Assistant kit.

Install

npm install @mosaic-home/capacitor-home-assistant @mosaic-home/ha-client
npx cap sync android

The Android library ships inside the npm package; npx cap sync adds it to the app's Gradle build. The native plugin is named HomeAssistant.

Use

import { authorizeUrl, exchangeCode, parseRedirect, type OAuthClient } from '@mosaic-home/ha-client';
import { capacitorHttp, discoverServers, nativeLogin, storeTokens } from '@mosaic-home/capacitor-home-assistant';

const client: OAuthClient = {
  clientId: 'https://example.org/my-app/',
  redirectUri: 'https://example.org/my-app/auth/callback',
};

// Home Assistants on the network, until stop() is called.
const stop = await discoverServers((server) => console.log(server.name, server.url));

// Home Assistant's login page; the redirect is caught inside the WebView and never loaded.
const baseUrl = 'http://homeassistant.local:8123';
const state = crypto.randomUUID();
const redirect = await nativeLogin(authorizeUrl(baseUrl, client, state), client.redirectUri, 'homeassistant.local');
const tokens = await exchangeCode(capacitorHttp, baseUrl, client, parseRedirect(redirect, client, state));

// Kept under tokens.<accountId>, where native code can read and refresh them.
await storeTokens('<the Home Assistant user id>', tokens);
stop();

secureStore holds any other secret the same way. loadTokens and forgetTokens read and remove an account's tokens. Off Android (a browser preview), login is unavailable, secureStore falls back to localStorage and capacitorHttp to fetch.

What it needs

• Capacitor 8 (@capacitor/core 8 or newer as a peer dependency).
• Android 8.0 (API 26) or newer, Java 21 for the build.
• An OAuth client id for your app: a web address whose redirect address is on the same host, so Home Assistant accepts it without fetching anything.

Licence

Apache-2.0.