homebridge-mynest 0.1.0

package/.env.example

@@ -0,0 +1,20 @@
+# Nest Account access token, used by the local verification script only.
+#
+# The plugin itself reads this value from the Homebridge platform config
+# (`accessToken`), not from the environment. This file exists so `npm run
+# verify` can talk to a live account without the token ever being typed into a
+# shell history or committed.
+#
+# How to obtain it:
+#   1. Sign in at https://home.nest.com in a browser.
+#   2. In the same browser, open https://home.nest.com/session
+#   3. Copy the value of the `access_token` field from the JSON response.
+#
+# The token grants full control of every thermostat and smoke alarm on the
+# account. Treat it like a password: never commit it, never paste it into an
+# issue report. Copy this file to `.env` (which is gitignored) to use it.
+NEST_ACCESS_TOKEN=
+
+# Optional. Set to 1 to talk to Nest's field-test environment
+# (home.ft.nest.com / grpc-web.ft.nest.com) instead of production.
+# NEST_FIELD_TEST=1

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project are documented here. From the first release onward, [release-please](https://github.com/googleapis/release-please) owns this file — do not hand-edit version headings after `0.1.0` ships.
+
+## [Unreleased]
+
+## 0.1.0
+
+Initial public release of **homebridge-mynest**.
+
+### Features
+
+- Nest Account `access_token` authentication (Google JWT / `ya29.` shapes rejected at config validation)
+- Dual transport: REST `app_launch` + `/v5/subscribe` merged with HTTP/2 Observe
+- Nest thermostats (read-only), Nest Protect, and Nest Temperature Sensors in HomeKit
+- Homebridge 2–safe characteristic updates via stored getters + `updateValue(...)`
+- Honest Protect occupancy (REST `auto_away` / ~10-minute presence; mains-powered only)
+- Smoke/CO published after Nest REST reports alarm state; REST outages and expired tokens keep tiles in HomeKit but mark them inactive/faulted rather than freezing a live all-clear or tearing services down
+- Accessory removal only after Nest-confirmed drops (Observe + REST two-strike / truncation guards); transport outages and REST-only boots do not bounce rooms or automations
+- Per-transport circuit breakers for sustained Nest edge failures
+- Opt-in diagnostics heartbeats (`diagnosticsInterval` / `structuredLogs`)
+- Observe device prune, rediscovery, and per-transport HTTP 403 budgets

package/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing
+
+Thanks for interest in improving `homebridge-mynest`.
+
+## Development setup
+
+```bash
+npm install
+npm test
+npm run build
+npm run lint
+```
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for architecture and [RELEASING.md](RELEASING.md) for the release-please / npm Trusted Publishing flow.
+
+Use Conventional Commits (`feat:`, `fix:`, `docs:`, `test:`, `chore:`, …).
+
+## Rules of the road
+
+- **Do not copy** code from `chrisjshull/homebridge-nest` or other Nest plugins. Reimplement from probes and Nest behaviour.
+- **No Google auth** in v1. Nest Account `access_token` only.
+- **No secrets in the repo.** Use `.env` (gitignored) for live scripts; never commit tokens or probe captures that contain account data.
+- **Life-safety honesty.** Do not invent Protect all-clear or motion from unverified Observe fields.
+- **Homebridge 2 update path.** Use `CharacteristicBinder` / `updateValue(reader())` — never `getValue()` for pushes, never `updateValue(characteristic.value)`.
+
+## Live verification
+
+```bash
+cp .env.example .env
+# paste NEST_ACCESS_TOKEN
+npm run verify
+```
+
+`verify` is read-only. Thermostat writes are not available yet.
+
+## Pull requests
+
+- Keep PRs focused
+- Include tests for behaviour changes
+- Update docs when user-facing semantics change (especially occupancy and smoke/CO)

package/DEVELOPMENT.md

@@ -0,0 +1,70 @@
+# Development
+
+## Architecture
+
+Two layers, meeting at the platform. Above it, accessories speak HomeKit. Below it, `api/` speaks Nest (REST + Observe) and knows nothing about HomeKit. The state layer between them is pure and fixture-testable.
+
+| Area | Purpose |
+| --- | --- |
+| `src/platform.ts` | Discovery, accessory lifecycle, coalesced updates |
+| `src/diagnostics/` | Opt-in health heartbeats and rollup (mirrors sibling plugins) |
+| `src/api/session.ts` | Nest Account session (`GET /session`) |
+| `src/api/rest.ts` | `app_launch` + `/v5/subscribe` |
+| `src/api/observe.ts` | HTTP/2 Observe stream |
+| `src/api/framing.ts` / `protobuf.ts` | Length-delimited frames and trait decode |
+| `src/api/transport.ts` | Independent REST + Observe run loops |
+| `src/state/*` | Observe∪REST merge, Protect/thermostat/sensor readers |
+| `src/accessories/*` | HomeKit accessories + HB2-safe `CharacteristicBinder` |
+| `src/utils/sanitizers.ts` | Central secret redaction |
+| `assets/protobuf/` | Vendored decode-only Nest schemas + ObserveTraits blob |
+
+## Design principles
+
+- **Nest Account tokens only.** Google JWT / `ya29.` shapes are rejected at config validation.
+- **Observe ∪ REST.** Neither transport is a superset; thermostats are Observe-first; Observe-only Protects must appear.
+- **Life-safety honesty.** No invented Protect all-clear or motion from unverified Observe fields.
+- **HB2 update path.** Store getters; push with `updateValue(reader())` — never `getValue()`, never `updateValue(characteristic.value)`.
+- **Dependency-light.** Runtime dependency is `protobufjs` only; `fetch` and `http2` are Node built-ins.
+- **Secrets never reach the log.** Tokens, Basic headers, and user ids are redacted.
+
+## Local workflow
+
+```bash
+npm install
+npm test
+npm run build
+npm run lint
+```
+
+Live read-only check (requires `.env` with `NEST_ACCESS_TOKEN` — never commit it):
+
+```bash
+cp .env.example .env
+npm run verify
+```
+
+`verify` drives compiled `dist/` against the live account and prints the merged inventory. It does not write setpoints. Treat its output as sensitive; prefer redacted paste into issues.
+
+## Protocol notes
+
+See [docs/PROTOCOL.md](docs/PROTOCOL.md) and [docs/AUTH.md](docs/AUTH.md). Arbitrary-looking constants in `src/settings.ts` are empirical; comments explain why they are what they are.
+
+### Bumping the pinned Nest client identity
+
+`USER_AGENT` (Chrome 77) and `WEB_APP_VERSION` are pinned because Nest's private backends check them. If production starts returning sustained HTTP 403s after a Nest edge change:
+
+1. Capture a fresh session from the Nest web app and note the `User-Agent` / app version strings it sends.
+2. Update the constants in `src/settings.ts` with a Conventional Commit explaining the Nest-side change.
+3. Run `npm run verify` against a live account before merging.
+
+Do not bump them casually — an incompatible schema version can change trait shapes this plugin cannot decode.
+
+## Tests
+
+Unit tests live under `tests/unit/` and use synthesized fixtures only — never live capture. Accessory tests run against real `hap-nodejs` services so the HB2 value-cache bug can actually reproduce.
+
+Integration tests live under `tests/integration/` and exercise discovery / transport wiring against fixtures (no live Nest account):
+
+```bash
+npm run test:integration
+```

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,146 @@
+# homebridge-mynest
+
+[![Tests](https://github.com/tbaur/homebridge-mynest/actions/workflows/test.yml/badge.svg)](https://github.com/tbaur/homebridge-mynest/actions/workflows/test.yml)
+[![npm version](https://img.shields.io/npm/v/homebridge-mynest?style=flat-square)](https://www.npmjs.com/package/homebridge-mynest)
+[![npm downloads](https://img.shields.io/npm/dt/homebridge-mynest?style=flat-square)](https://www.npmjs.com/package/homebridge-mynest)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20-green)](https://nodejs.org)
+[![Homebridge](https://img.shields.io/badge/homebridge-%3E%3D1.6.0%20%7C%7C%202.x-purple)](https://homebridge.io)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+
+Expose Nest thermostats, Nest Protect smoke/CO alarms, and Nest Temperature Sensors in Apple HomeKit through Homebridge, using a **Nest Account** access token only (no Google cookie / `issueToken` auth).
+
+## Features
+
+### Device Support
+
+- **Thermostats** — Current temperature, mode, activity, setpoints, humidity when Nest reports it (read-only in this version)
+- **Nest Protect** — Smoke and CO from REST when available; battery / online from REST and/or Observe; optional occupancy and Protect temperature
+- **Temperature Sensors** — Nest Temperature Sensor (kryptonite) pucks
+- **Dual transport** — Merges Nest REST subscribe with HTTP/2 Observe so Observe-only devices still appear
+
+### Honesty about Nest's APIs
+
+- **Occupancy is not motion** — Nest publishes `auto_away` for mains-powered Protects: roughly a ten-minute presence verdict. Battery Protects, power-unknown Protects, and Observe-only Protects get no occupancy sensor rather than a stuck "empty house"; when REST later goes stale, a last occupancy reading stays published but is marked inactive/faulted
+- **Smoke/CO honesty without accessory churn** — Observe-only Protects omit smoke/CO until REST reports alarm state; if REST later goes down, tiles stay in HomeKit (rooms/automations keep their targets) but are marked inactive/faulted rather than freezing a live all-clear. Battery and online may remain from Observe
+- **Thermostats are Observe-first** — Modern Nest thermostats may be missing from REST entirely; this plugin does not rely on REST-only discovery for HVAC
+
+### Reliability
+
+- **No accessory churn on outages or token expiry** — Devices leave HomeKit only after Nest-confirmed drops (two-strike + truncation guards on Observe and REST). A cloud blip, REST-only boot, or expired access token stops updates but does not unregister thermostats, Protects, or temp sensors (paste a fresh token and restart)
+- **Circuit breakers** — Independent REST and Observe breakers fail fast when Nest's edge is returning sustained 5xx / network failures, then probe again after a short cooldown (auth and 403 paths keep their own handling)
+- **Diagnostics** *(optional)* — Opt-in health/activity heartbeats, boot/shutdown snapshots, and healthy/degraded transitions in the Homebridge log (REST + Observe transport gauges, breaker state, device inventory, API latency)
+
+### Quality
+
+<!-- Canonical test count lives here only; keep other docs number-free to avoid multi-place updates. -->
+- **Homebridge 2 safe** — Live updates use stored getters + `updateValue(...)`, not removed `getValue()` or stale `.value` reads
+- **412 Tests** — Jest suite with an 80% coverage gate across statements, branches, functions, and lines
+- **Strict TypeScript** — `strict` mode with unused locals/params and no implicit returns
+- **Secret hygiene** — Access tokens are redacted from logs
+- **No analytics** — Zero tracking or data collection
+
+## Quick Start
+
+### 1. Install
+
+**Homebridge UI** (recommended): Plugins → Search `mynest` → Install
+
+**Command line:**
+
+```bash
+npm install -g homebridge-mynest
+```
+
+### 2. Get a Nest Account token
+
+You need a Nest Account (not Google-only) access token from [home.nest.com/session](https://home.nest.com/session). Steps and threat model: [docs/AUTH.md](docs/AUTH.md).
+
+Prefer treating that token like a password; Nest Account sessions are account-scoped credentials.
+
+### 3. Configure
+
+Use the Homebridge UI, or add the platform to `config.json`:
+
+```json
+{
+  "platforms": [
+    {
+      "platform": "MyNest",
+      "name": "MyNest",
+      "accessToken": "paste-access_token-from-home.nest.com/session"
+    }
+  ]
+}
+```
+
+### 4. Restart Homebridge
+
+Thermostats, Protects, and temperature sensors appear in the Home app as Nest reports them.
+
+## Supported Devices
+
+| Nest device | HomeKit accessory | Notes |
+| --- | --- | --- |
+| Thermostat | Thermostat | Read-only; Observe is source of truth |
+| Nest Protect | Smoke + CO (+ optional occupancy / temp) | Smoke/CO require REST `topaz`; occupancy is ~10-minute presence |
+| Temperature Sensor | Temperature Sensor | Battery + temperature |
+
+Cameras, doorbells, locks, and Home/Away structure switches are out of scope for v1.
+
+## Configuration Options
+
+`name` is required by Homebridge verified plugins and identifies this instance in the logs (defaults to `MyNest`).
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `name` | `MyNest` | Required. Plugin instance name shown in Homebridge logs. |
+| `accessToken` | — | Required. Nest Account `access_token` from [docs/AUTH.md](docs/AUTH.md). |
+| `allowThermostatControl` | `false` | Reserved; writes are not supported yet (warns if enabled). |
+| `exposeProtectOccupancy` | `true` | Occupancy from REST `auto_away` when Nest computes it on a mains-powered Protect. |
+| `exposeProtectTemperature` | `false` | Temperature/humidity measured by each Protect. |
+| `ignoredDeviceIds` | `[]` | Device IDs or serials to leave out of HomeKit. |
+| `fieldTest` | `false` | Use Nest field-test hosts. |
+| `diagnosticsInterval` | `0` | Seconds between health heartbeats in the log; `0` off, else `30`–`3600`. |
+| `structuredLogs` | `false` | When diagnostics are enabled, also emit a machine-readable JSON line alongside each human summary. |
+| `debug` | `false` | Verbose logging; tokens are redacted. |
+
+## Protect occupancy
+
+Nest does not expose a reliable Protect motion event stream to third-party clients. What this plugin publishes (when REST `auto_away` exists on a mains-powered Protect) is Nest's own presence hold-off — on the order of **ten minutes** after the room empties, clearing when activity is seen again. Do not build automations that expect pathlight-speed motion.
+
+## Not Working?
+
+1. **Authentication error** — Token missing, truncated, Google JWT/`ya29.`, or revoked. Capture a fresh Nest Account token ([docs/AUTH.md](docs/AUTH.md)).
+2. **Thermostat missing** — Modern thermostats are Observe-only on some accounts. With default logging the plugin warns within about a minute if Observe produced no frames; set `debug: true` for stream detail, or run `npm run verify`.
+3. **Protect without smoke/CO** — Likely Observe-only (missing from REST). The accessory still appears; alarm tiles wait for REST.
+4. **No occupancy** — Battery Protect, power unknown, Observe-only Protect, or `exposeProtectOccupancy` off.
+
+## Security
+
+This plugin holds a Nest Account `access_token` in Homebridge's plaintext `config.json`. That token is account-scoped Nest credentials — anyone who can read the file can act as the Nest web app for the home. Secure the host, prefer rotating the token if it may have leaked, and never paste tokens into issues or logs.
+
+Details: [SECURITY.md](SECURITY.md) and [docs/AUTH.md](docs/AUTH.md).
+
+Nest publishes no consumer API and can change or revoke sessions without notice. This plugin uses Nest Account tokens only and rejects Google cookie / `ya29.` shapes on purpose.
+
+## Requirements
+
+- Node.js 20 or newer
+- Homebridge 1.6 or newer, including Homebridge 2.x
+- A Nest Account (not Google-only) with an `access_token` from [home.nest.com/session](https://home.nest.com/session)
+
+## More Info
+
+- [Authentication](docs/AUTH.md) — capturing the Nest Account token
+- [Protocol notes](docs/PROTOCOL.md) — reverse-engineered Nest behaviour
+- [Development](DEVELOPMENT.md) — architecture and local setup
+- [Contributing](CONTRIBUTING.md)
+- [Security policy](SECURITY.md)
+- [Changelog](CHANGELOG.md)
+- [Report issues](https://github.com/tbaur/homebridge-mynest/issues)
+
+## License
+
+Copyright 2026 tbaur
+
+Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) file for details.

package/RELEASING.md

@@ -0,0 +1,55 @@
+# Releasing
+
+Releases are fully automated with [release-please](https://github.com/googleapis/release-please). Versions, `CHANGELOG.md`, git tags, GitHub Releases, and `npm publish` are all derived from commit messages — none are edited or run by hand.
+
+## Flow
+
+1. A branch is created and changes are committed.
+2. A PR is opened with a **Conventional Commit title**. The title determines the next version when the PR is squash-merged into `main`:
+
+   | PR title prefix | Example | Version bump (pre-1.0) |
+   | --- | --- | --- |
+   | `fix:` | `fix: rate-limit REST subscribe success path` | patch (0.1.0 → 0.1.1) |
+   | `feat:` | `feat: thermostat write path behind confirm` | patch (0.1.0 → 0.1.1) |
+   | `feat!:` / `fix!:` or a `BREAKING CHANGE:` footer | `feat!: drop Node 20` | minor (0.1.0 → 0.2.0) |
+   | `chore:`, `docs:`, `refactor:`, `test:`, `ci:` | `docs: fix typo` | no release |
+
+   The bumps above are damped while the version is below `1.0.0`, because `release-please-config.json` sets `bump-minor-pre-major` and `bump-patch-for-minor-pre-major`. Once `1.0.0` ships, the same prefixes resume their normal meaning.
+
+3. The **Tests** workflow runs on the PR (matrix: Node 20, 22, 24, plus a security audit). The PR is squash-merged to `main`.
+4. **release-please** opens or updates a **Release PR** titled `chore(main): release X.Y.Z`.
+5. Merging the Release PR triggers `release.yml`, which creates the `vX.Y.Z` tag, publishes a GitHub Release, and runs `npm publish` with provenance on Node 24.
+
+## Branch protection
+
+`main` is protected with settings chosen to be compatible with the automated flow above:
+
+- **Require a pull request before merging** (0 required approvals) — keeps direct pushes off `main` without blocking a solo maintainer.
+- **Block force-pushes and deletions.**
+- **No required status checks.** The Tests workflow runs on every code PR and is visible there, but it is intentionally *not* a hard merge gate. The Release PR is opened by the built-in `GITHUB_TOKEN`, and GitHub does not trigger workflows for such PRs (loop prevention), so a required check would leave every Release PR permanently unmergeable. The `publish` job re-runs build → lint → test before `npm publish`, so releases are still gated on a green build.
+
+## Publishing authentication
+
+Publishing uses **npm Trusted Publishing (OIDC)** — there is no `NPM_TOKEN` secret. Link the package to this repo's `release.yml` workflow on npmjs.com before the first Release PR is merged:
+
+- Package → **Settings → Trusted Publisher**
+- GitHub Actions publisher: organization/user `tbaur`, repository `homebridge-mynest`, workflow `release.yml`, no environment.
+
+This link only needs to exist before the first Release PR is merged; it does not need to be reconfigured per release.
+
+## Notes
+
+- **PR titles drive releases.** With squash merges, the PR title becomes the commit release-please reads. `chore:`/`docs:`/`ci:` titles intentionally produce no release.
+- **The Release PR does not re-run the Tests workflow.** GitHub does not trigger workflows for PRs opened by the built-in token (loop prevention). The code was already tested on its own PR, and the `publish` job builds, lints, and tests again before publishing, so nothing ships untested.
+- **Do not hand-edit** `CHANGELOG.md` or the `package.json` version after the first public release; release-please owns both. Version source of truth is `.release-please-manifest.json`.
+- **`dist/` is committed** so `npm install` from git works. CI fails if `dist/` drifts from `src/`.
+
+## Manual fallback
+
+Manual publishing is rarely needed and bypasses CI provenance and manifest syncing. If unavoidable:
+
+```bash
+npm run clean && npm run build && npm run lint && npm test
+npm publish --dry-run   # verify contents
+npm publish             # requires npm login + OTP
+```

package/SECURITY.md

@@ -0,0 +1,49 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported         |
+| ------- | ----------------- |
+| 0.1.x   | ✅ Active support |
+
+While the plugin is pre-1.0, only the most recent release is supported. Fixes are shipped forward rather than backported.
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability, please report it responsibly:
+
+1. **Do NOT open a public issue**
+2. Email the maintainer directly or use GitHub's [private vulnerability reporting](https://github.com/tbaur/homebridge-mynest/security/advisories/new)
+3. Include:
+   - Description of the vulnerability
+   - Steps to reproduce
+   - Potential impact
+   - Any suggested fixes
+
+## The Nest Account access token
+
+How to capture the token is in [docs/AUTH.md](docs/AUTH.md). This section is the threat model.
+
+Nest publishes no consumer API. This plugin authenticates with a Nest Account `access_token` copied from `https://home.nest.com/session`. Understand what that token is before you configure the plugin:
+
+- **It is account-scoped Nest credentials**, not a HomeKit pairing code. Anyone who has it can act as the Nest web app for that account.
+- **It is stored in plaintext.** Homebridge keeps plugin configuration in `config.json` on disk, unencrypted. Anyone who can read that file — or a backup of it — holds a durable credential to the Nest home.
+- **Google cookies and OAuth tokens are rejected on purpose.** They cover a broader Google identity than Nest Account access and are a different auth surface this plugin does not implement.
+
+Treat the token as a password-equivalent credential. Do not paste it into issues, logs, screenshots, or chat.
+
+**Revoking it.** Sign out Nest sessions / rotate Nest account credentials from Nest's account settings, then capture a fresh token and update Homebridge.
+
+## Security Measures
+
+This plugin implements:
+
+- Nest Account tokens only — Google JWT / `ya29.` shapes are rejected at config validation
+- Secret redaction in structured logs
+- Transport URL host allowlisting before the session token is sent
+- Read-only thermostat publication until a write path is proven against a live device
+- No analytics or telemetry
+
+## Scope limits
+
+Cameras, doorbells, Yale locks, and Google-account-only homes are out of scope. Life-safety alarm state for Protects is only published while Nest REST can refresh it; Observe-only units and Protects whose REST feed is down do not keep a frozen all-clear.