@camstack/addon-provider-homeassistant 1.2.18 → 1.2.20

package/dist/addon.js

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_dist = require("./dist-DuKJzmrJ.js");
+const require_dist = require("./dist-Bz5ENMVc.js");
 let node_crypto = require("node:crypto");
 let node_zlib = require("node:zlib");
 //#region src/ha-device-source.ts

package/dist/addon.mjs

@@ -1,4 +1,4 @@
-import { $ as tamperCapability, A as eventEmitterCapability, B as motionCapability, C as connectivityCapability, Ct as url, D as deviceAdoptionCapability, E as coverCapability, F as humiditySensorCapability, H as notificationOutputCapability, I as imageCapability, J as presenceCapability, K as powerMeterCapability, L as lawnMowerControlCapability, M as floodCapability, N as gasCapability, P as humidifierCapability, Q as switchCapability, R as lockControlCapability, S as colorCapability, St as unknown, T as controlCapability, U as notifierCapability, V as normalizeUnit, W as numericSensorCapability, X as scriptRunnerCapability, Y as pressureSensorCapability, Z as smokeCapability, _ as brokerCapability, _t as number, a as EnumSensorDateTimeFormatSchema, at as waterHeaterCapability, b as carbonMonoxideCapability, bt as string, c as addonRoutesCapability, d as ambientLightSensorCapability, dt as DeviceType, et as temperatureSensorCapability, f as automationControlCapability, ft as createEvent, g as brightnessCapability, gt as literal, h as binaryCapability, ht as discriminatedUnion, it as vibrationCapability, j as fanControlCapability, k as enumSensorCapability, l as airQualitySensorCapability, lt as DeviceFeature, m as bestLocationMatch, mt as array, n as BaseDeviceProvider, nt as vacuumControlCapability, o as TargetSchema, ot as weatherCapability, p as batteryCapability, pt as _enum, q as prepareNotification, rt as valveCapability, s as accessoriesCapability, st as errMsg, t as BaseDevice, tt as updateCapability, u as alarmPanelCapability, ut as DeviceRole, v as buildAddonRouteProvider, vt as object, w as contactCapability, wt as EventCategory, x as climateControlCapability, xt as union, y as buttonCapability, yt as record, z as mediaPlayerCapability } from "./dist-UfT_fD3-.mjs";
+import { $ as tamperCapability, A as eventEmitterCapability, B as motionCapability, C as connectivityCapability, Ct as url, D as deviceAdoptionCapability, E as coverCapability, F as humiditySensorCapability, H as notificationOutputCapability, I as imageCapability, J as presenceCapability, K as powerMeterCapability, L as lawnMowerControlCapability, M as floodCapability, N as gasCapability, P as humidifierCapability, Q as switchCapability, R as lockControlCapability, S as colorCapability, St as unknown, T as controlCapability, U as notifierCapability, V as normalizeUnit, W as numericSensorCapability, X as scriptRunnerCapability, Y as pressureSensorCapability, Z as smokeCapability, _ as brokerCapability, _t as number, a as EnumSensorDateTimeFormatSchema, at as waterHeaterCapability, b as carbonMonoxideCapability, bt as string, c as addonRoutesCapability, d as ambientLightSensorCapability, dt as DeviceType, et as temperatureSensorCapability, f as automationControlCapability, ft as createEvent, g as brightnessCapability, gt as literal, h as binaryCapability, ht as discriminatedUnion, it as vibrationCapability, j as fanControlCapability, k as enumSensorCapability, l as airQualitySensorCapability, lt as DeviceFeature, m as bestLocationMatch, mt as array, n as BaseDeviceProvider, nt as vacuumControlCapability, o as TargetSchema, ot as weatherCapability, p as batteryCapability, pt as _enum, q as prepareNotification, rt as valveCapability, s as accessoriesCapability, st as errMsg, t as BaseDevice, tt as updateCapability, u as alarmPanelCapability, ut as DeviceRole, v as buildAddonRouteProvider, vt as object, w as contactCapability, wt as EventCategory, x as climateControlCapability, xt as union, y as buttonCapability, yt as record, z as mediaPlayerCapability } from "./dist-BSQpoIVg.mjs";
 import { randomUUID } from "node:crypto";
 import { brotliCompressSync, deflateSync, gzipSync } from "node:zlib";
 //#region src/ha-device-source.ts

package/dist/{dist-UfT_fD3-.mjs → dist-BSQpoIVg.mjs}

@@ -15351,21 +15351,32 @@ object({
 *    core, and no per-integration branch anywhere: `/api/oauth2/authorize` and
 *    `/api/oauth2/integrations` are built from this collection alone.
 *
-* **Scopes.** `requestedScopes` is baked into every token this integration is
-* ever issued and the operator consents to it once. Derive it from the tRPC
-* paths the client calls **with that token**, against `METHOD_ACCESS_MAP`, and
-* prefer a narrow `capability:` scope to a `category:` one unless the client
-* genuinely needs a whole family. A category scope grants every future member
+* **Scopes. `requestedScopes` has exactly ONE meaning: what the integration
+* NEEDS to function.** Not a blast radius, not a conservative
+* under-declaration, not a description of some other path the addon happens to
+* have. Derive it from what the client actually calls **with this token** —
+* every tRPC path against `METHOD_ACCESS_MAP`, plus an `addon:` grant for every
+* addon HTTP route it posts to — and write the call that justifies each entry
+* next to it. Two integrations once used this field to mean two different
+* things; the operator ruled there is one meaning, and any third integration
+* inherits it (2026-08-09).
+*
+* This is not documentation, it is the ENFORCEMENT INPUT. Since
+* [D103](../../../../docs/decisions/adr-0103.md) the `/addon/:addonId/*` gate
+* checks an integration token's grant before letting it reach an
+* `access: 'authenticated'` route, so an **under-declaration is an integration
+* that stops working** — a missing `addon:` entry means `403 Token scope
+* mismatch` on every control the client tries to actuate. Widen the descriptor
+* honestly rather than weakening a check to make a route pass.
+*
+* Prefer a narrow `capability:` scope to a `category:` one unless the client
+* genuinely needs a whole family; a category scope grants every future member
 * of that category too. `category:system [create]` has been rejected once and
 * should stay rejected: it hands `addons.installPackage` to an integration.
 *
-* What it does NOT cover: calls the ADDON makes over `ctx.api`, which run as
-* the addon and are not scope-checked. Alexa's descriptor is narrower than
-* Home Assistant's for exactly that reason — its Lambda posts directives and
-* the addon does the work, while the Home Assistant component calls tRPC
-* directly with the token. So `requestedScopes` describes the blast radius of
-* the GRANT, not the reach of the integration; do not widen one to describe the
-* other.
+* Calls the ADDON itself makes over `ctx.api` run as the addon and are not
+* scope-checked, so they are not what this field describes — but reaching the
+* addon's route in the first place IS, and that is the entry to declare.
 *
 * **The boot window.** An addon registers its provider after its runner forks
 * and initialises, so between hub start and that moment this collection is
@@ -15406,7 +15417,30 @@ var OauthIntegrationDescriptorSchema = object({
 	*  present, /api/oauth2/authorize bakes THIS into the code instead of the
 	*  hub-global `publicHubUrl()`, so a forked exporter addon (which can't set
 	*  the hub's env) drives the claim that its cloud Lambda routes back on. */
-	hubUrl: string().optional()
+	hubUrl: string().optional(),
+	/**
+	* How long a REFRESH token issued for this integration lives — seconds, or
+	* `'never'` for a token minted with no `exp` claim at all. Omit to keep the
+	* 30-day default, which is what every link used before this field existed.
+	*
+	* Declared here for the same reason `requestedScopes` is: the integration
+	* knows what it needs. Amazon's account linking and a Home Assistant config
+	* entry are both meant to survive indefinitely, and re-linking is a manual
+	* user action, so a 30-day expiry silently unlinks a working integration.
+	*
+	* **The security posture, stated so it is owned deliberately.** A refresh
+	* token that never expires is permanent access if it leaks. What bounds it is
+	* revocation, not time: `oauthRefresh` re-reads the session on every use and
+	* returns `null` once `revokedAt` is set, as does `oauthVerifyAccessToken`.
+	* The one gap is the ACCESS token — it is a plain signed JWT that nothing
+	* re-checks against the session on the `/trpc` and `/addon/*` paths, so
+	* revoking a link takes effect there only after its remaining hour. That hour
+	* is why the access TTL is not configurable.
+	*
+	* The value is baked into the authorization code at `/authorize` and travels
+	* on the tokens, so editing this field changes FUTURE links only.
+	*/
+	refreshTokenTtlSec: union([number().int().positive(), literal("never")]).optional()
 });
 var oauthIntegrationCapability = {
 	name: "oauth-integration",
@@ -18549,11 +18583,29 @@ var SsoBridgeClaimsSchema = object({
 	codeChallenge: string().optional(),
 	/** OAuth session registry id — set on `oauth-access`/`oauth-refresh`
 	*  tokens so the verify path can check the session is not revoked. */
-	sessionId: string().optional()
+	sessionId: string().optional(),
+	/**
+	* The refresh lifetime this LINK was created with, in seconds, or `'never'`.
+	* Baked into the code at `/authorize` from the integration's descriptor and
+	* carried forward so `oauthRefresh` re-mints with the same lifetime. It rides
+	* on the token rather than being re-read from the descriptor on purpose:
+	* editing a descriptor must not retroactively extend or shorten a link the
+	* operator already consented to.
+	*/
+	refreshTtl: union([number().int().positive(), literal("never")]).optional()
 });
 method(object({
 	claims: SsoBridgeClaimsSchema,
-	ttlSec: number().int().positive().optional()
+	/**
+	* Seconds, or `'never'` for a token minted with NO `exp` claim.
+	*
+	* `'never'` is a literal rather than `undefined`/`0` because omitting
+	* this field already means "the 5-minute SSO hand-off default", and
+	* `jwt.sign` THROWS on `{ expiresIn: undefined }` — a "no expiry" that
+	* went through the numeric path would fail at mint time and break
+	* linking rather than produce an eternal token.
+	*/
+	ttlSec: union([number().int().positive(), literal("never")]).optional()
 }), object({ token: string() })), method(object({ token: string() }), SsoBridgeClaimsSchema.nullable());
 var ProviderListEntrySchema = discriminatedUnion("shouldSaveDiskSpace", [object({
 	providerId: string().min(1),
@@ -25834,7 +25886,12 @@ method(_void(), array(UserSummarySchema), { auth: "admin" }), method(CreateUserI
 	hubUrl: string(),
 	/** PKCE (RFC 7636) S256 challenge. Baked into the signed code; a code
 	*  that carries one can ONLY be exchanged with the matching verifier. */
-	codeChallenge: string().optional()
+	codeChallenge: string().optional(),
+	/** The integration's declared refresh lifetime — seconds, or `'never'`.
+	*  From `OauthIntegrationDescriptor.refreshTokenTtlSec`. Baked into the
+	*  code so the link carries its own lifetime; omit for the 30-day
+	*  default. */
+	refreshTtlSec: union([number().int().positive(), literal("never")]).optional()
 }), object({ code: string() }), {
 	kind: "mutation",
 	access: "create"

package/dist/{dist-DuKJzmrJ.js → dist-Bz5ENMVc.js}

@@ -15351,21 +15351,32 @@ object({
 *    core, and no per-integration branch anywhere: `/api/oauth2/authorize` and
 *    `/api/oauth2/integrations` are built from this collection alone.
 *
-* **Scopes.** `requestedScopes` is baked into every token this integration is
-* ever issued and the operator consents to it once. Derive it from the tRPC
-* paths the client calls **with that token**, against `METHOD_ACCESS_MAP`, and
-* prefer a narrow `capability:` scope to a `category:` one unless the client
-* genuinely needs a whole family. A category scope grants every future member
+* **Scopes. `requestedScopes` has exactly ONE meaning: what the integration
+* NEEDS to function.** Not a blast radius, not a conservative
+* under-declaration, not a description of some other path the addon happens to
+* have. Derive it from what the client actually calls **with this token** —
+* every tRPC path against `METHOD_ACCESS_MAP`, plus an `addon:` grant for every
+* addon HTTP route it posts to — and write the call that justifies each entry
+* next to it. Two integrations once used this field to mean two different
+* things; the operator ruled there is one meaning, and any third integration
+* inherits it (2026-08-09).
+*
+* This is not documentation, it is the ENFORCEMENT INPUT. Since
+* [D103](../../../../docs/decisions/adr-0103.md) the `/addon/:addonId/*` gate
+* checks an integration token's grant before letting it reach an
+* `access: 'authenticated'` route, so an **under-declaration is an integration
+* that stops working** — a missing `addon:` entry means `403 Token scope
+* mismatch` on every control the client tries to actuate. Widen the descriptor
+* honestly rather than weakening a check to make a route pass.
+*
+* Prefer a narrow `capability:` scope to a `category:` one unless the client
+* genuinely needs a whole family; a category scope grants every future member
 * of that category too. `category:system [create]` has been rejected once and
 * should stay rejected: it hands `addons.installPackage` to an integration.
 *
-* What it does NOT cover: calls the ADDON makes over `ctx.api`, which run as
-* the addon and are not scope-checked. Alexa's descriptor is narrower than
-* Home Assistant's for exactly that reason — its Lambda posts directives and
-* the addon does the work, while the Home Assistant component calls tRPC
-* directly with the token. So `requestedScopes` describes the blast radius of
-* the GRANT, not the reach of the integration; do not widen one to describe the
-* other.
+* Calls the ADDON itself makes over `ctx.api` run as the addon and are not
+* scope-checked, so they are not what this field describes — but reaching the
+* addon's route in the first place IS, and that is the entry to declare.
 *
 * **The boot window.** An addon registers its provider after its runner forks
 * and initialises, so between hub start and that moment this collection is
@@ -15406,7 +15417,30 @@ var OauthIntegrationDescriptorSchema = object({
 	*  present, /api/oauth2/authorize bakes THIS into the code instead of the
 	*  hub-global `publicHubUrl()`, so a forked exporter addon (which can't set
 	*  the hub's env) drives the claim that its cloud Lambda routes back on. */
-	hubUrl: string().optional()
+	hubUrl: string().optional(),
+	/**
+	* How long a REFRESH token issued for this integration lives — seconds, or
+	* `'never'` for a token minted with no `exp` claim at all. Omit to keep the
+	* 30-day default, which is what every link used before this field existed.
+	*
+	* Declared here for the same reason `requestedScopes` is: the integration
+	* knows what it needs. Amazon's account linking and a Home Assistant config
+	* entry are both meant to survive indefinitely, and re-linking is a manual
+	* user action, so a 30-day expiry silently unlinks a working integration.
+	*
+	* **The security posture, stated so it is owned deliberately.** A refresh
+	* token that never expires is permanent access if it leaks. What bounds it is
+	* revocation, not time: `oauthRefresh` re-reads the session on every use and
+	* returns `null` once `revokedAt` is set, as does `oauthVerifyAccessToken`.
+	* The one gap is the ACCESS token — it is a plain signed JWT that nothing
+	* re-checks against the session on the `/trpc` and `/addon/*` paths, so
+	* revoking a link takes effect there only after its remaining hour. That hour
+	* is why the access TTL is not configurable.
+	*
+	* The value is baked into the authorization code at `/authorize` and travels
+	* on the tokens, so editing this field changes FUTURE links only.
+	*/
+	refreshTokenTtlSec: union([number().int().positive(), literal("never")]).optional()
 });
 var oauthIntegrationCapability = {
 	name: "oauth-integration",
@@ -18549,11 +18583,29 @@ var SsoBridgeClaimsSchema = object({
 	codeChallenge: string().optional(),
 	/** OAuth session registry id — set on `oauth-access`/`oauth-refresh`
 	*  tokens so the verify path can check the session is not revoked. */
-	sessionId: string().optional()
+	sessionId: string().optional(),
+	/**
+	* The refresh lifetime this LINK was created with, in seconds, or `'never'`.
+	* Baked into the code at `/authorize` from the integration's descriptor and
+	* carried forward so `oauthRefresh` re-mints with the same lifetime. It rides
+	* on the token rather than being re-read from the descriptor on purpose:
+	* editing a descriptor must not retroactively extend or shorten a link the
+	* operator already consented to.
+	*/
+	refreshTtl: union([number().int().positive(), literal("never")]).optional()
 });
 method(object({
 	claims: SsoBridgeClaimsSchema,
-	ttlSec: number().int().positive().optional()
+	/**
+	* Seconds, or `'never'` for a token minted with NO `exp` claim.
+	*
+	* `'never'` is a literal rather than `undefined`/`0` because omitting
+	* this field already means "the 5-minute SSO hand-off default", and
+	* `jwt.sign` THROWS on `{ expiresIn: undefined }` — a "no expiry" that
+	* went through the numeric path would fail at mint time and break
+	* linking rather than produce an eternal token.
+	*/
+	ttlSec: union([number().int().positive(), literal("never")]).optional()
 }), object({ token: string() })), method(object({ token: string() }), SsoBridgeClaimsSchema.nullable());
 var ProviderListEntrySchema = discriminatedUnion("shouldSaveDiskSpace", [object({
 	providerId: string().min(1),
@@ -25834,7 +25886,12 @@ method(_void(), array(UserSummarySchema), { auth: "admin" }), method(CreateUserI
 	hubUrl: string(),
 	/** PKCE (RFC 7636) S256 challenge. Baked into the signed code; a code
 	*  that carries one can ONLY be exchanged with the matching verifier. */
-	codeChallenge: string().optional()
+	codeChallenge: string().optional(),
+	/** The integration's declared refresh lifetime — seconds, or `'never'`.
+	*  From `OauthIntegrationDescriptor.refreshTokenTtlSec`. Baked into the
+	*  code so the link carries its own lifetime; omit for the 30-day
+	*  default. */
+	refreshTtlSec: union([number().int().positive(), literal("never")]).optional()
 }), object({ code: string() }), {
 	kind: "mutation",
 	access: "create"