pydanalock-cloud 0.5.0__tar.gz

pydanalock_cloud-0.5.0/.github/pull_request_template.md

@@ -0,0 +1,18 @@
+## Summary
+
+<!-- What does this PR change? Link the feature spec: specs/NNNN-slug.md -->
+
+## Spec-driven checklist
+
+- [ ] Feature spec exists (`specs/NNNN-slug.md`) and has status `approved`
+- [ ] Tests written before implementation (TDD), failing first
+- [ ] API responses covered by recorded fixtures (no live cloud in unit tests)
+- [ ] Live tests stay behind the `live` marker
+- [ ] `ruff check .`, `ruff format --check .`, `mypy`, `pytest -m "not live"` pass
+- [ ] Skeptic review completed: verdict `APPROVED` (or `NITS` only)
+- [ ] No secrets committed (tokens, keys, credentials); placeholders only in examples
+- [ ] Logs never contain tokens or keys
+
+## Commit style
+
+Conventional Commits (`feat:`, `fix:`, `docs:`, `test:`, `chore:`, `refactor:`).

pydanalock_cloud-0.5.0/.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Ruff lint
+        run: ruff check .
+      - name: Ruff format
+        run: ruff format --check .
+      - name: Mypy
+        run: mypy
+      - name: Tests
+        run: pytest -m "not live"
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[release]"
+      - name: Build
+        run: python -m build
+      - name: Twine check
+        run: twine check dist/*

pydanalock_cloud-0.5.0/.github/workflows/publish.yml

@@ -0,0 +1,46 @@
+# Publishes to PyPI via Trusted Publishing (OIDC) when a GitHub Release is published.
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -U "build>=1.2" "twine>=5"
+      - name: Build
+        run: python -m build
+      - name: Twine check
+        run: twine check dist/*
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pydanalock_cloud-0.5.0/.github/workflows/testpypi.yml

@@ -0,0 +1,47 @@
+# Publishes to TestPyPI via Trusted Publishing (OIDC); manual dry run before a release.
+name: TestPyPI
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -U "build>=1.2" "twine>=5"
+      - name: Build
+        run: python -m build
+      - name: Twine check
+        run: twine check dist/*
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

pydanalock_cloud-0.5.0/.gitignore

@@ -0,0 +1,26 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# Environments
+.venv/
+venv/
+
+# Tooling caches
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Local secrets (never commit)
+*.local.json
+
+# Editors / OS
+.DS_Store
+.idea/
+.vscode/

pydanalock_cloud-0.5.0/AGENTS.md

@@ -0,0 +1,116 @@
+# AGENTS.md — pydanalock-cloud
+
+Working agreement for humans and AI agents contributing to this repository.
+
+## 1. Role in the group
+
+This repository is part of a group of projects that build a self-hosted
+control stack for Danalock V3 smart locks:
+
+| Repository | Role | Visibility | Language |
+|---|---|---|---|
+| `pydanalock-ble` | BLE client library for the Danalock V3 lock | public | English |
+| `pydanalock-cloud` (this repo) | Cloud API client (OAuth2, devices, keys) | public | English |
+| `danalock-ble-ha-integration` | Home Assistant custom integration, consumes both libraries | public | English |
+
+`pydanalock-ble` and `pydanalock-cloud` are independent of each other; key
+material is passed between them as opaque bytes (group contract type
+`DeviceKey`: serial, login_blob, broadcast_key, validity, permissions). This
+repository is the producer side of `DeviceKey`.
+
+## 2. Language
+
+All repository text is English: code, comments, docstrings, documentation,
+commit messages, and review notes.
+
+## 3. Stack and commands
+
+- Python >= 3.11, hatchling, src-layout (`src/pydanalock/cloud/`), PEP 420
+  namespace package `pydanalock` shared with `pydanalock-ble`.
+- Runtime dependency: `httpx>=0.28`; dev tools: pytest, pytest-asyncio, ruff,
+  mypy (strict for `src/`).
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/ruff check .
+.venv/bin/ruff format --check .
+.venv/bin/mypy
+.venv/bin/pytest -m "not live"
+```
+
+Live tests (real cloud, real credentials) carry the `live` marker and are run
+manually only: `.venv/bin/pytest -m live`. Credentials come from the
+environment: `DANALOCK_USERNAME`, `DANALOCK_PASSWORD`.
+
+## 4. Spec-driven development (SDD)
+
+- Every feature starts with a spec in `specs/NNNN-slug.md` (zero-padded
+  number, short slug). Status lifecycle: `draft → approved → implemented →
+  superseded`.
+- Implementation without an `approved` spec is forbidden. Specs marked
+  "implementation pending research" must not be implemented until they move to
+  `approved`.
+- Spec template: Summary / Motivation / Requirements (MUST/SHOULD) / Design /
+  API / Test plan / Acceptance criteria / Out of scope / Status.
+- Moving a spec from `draft` to `approved` is a reviewable change (PR or
+  recorded decision in the conversation).
+
+## 5. Test-driven development (TDD)
+
+- Tests are written first and must fail before the implementation exists.
+- API responses are covered by recorded fixtures via an httpx mock transport;
+  unit tests never touch the production API.
+- A merge requires a fully green run of all gate commands (§3).
+
+## 6. Git process
+
+- Default branch: `master`. Direct commits to `master` are forbidden (the
+  initial scaffold import is the only exception).
+- One feature = one branch `feat/NNNN-slug` containing the spec, the tests,
+  and the implementation together.
+- Commit messages follow Conventional Commits (`feat:`, `fix:`, `docs:`,
+  `test:`, `chore:`, `refactor:`).
+- Merge into `master` only after the review gate (§7), squash-merge, then
+  delete the feature branch.
+
+## 7. Review gate (mandatory)
+
+A feature branch may merge into `master` only when both hold:
+
+1. A full local run is green (§3/§5).
+2. A skeptic review returns no `BLOCKING` findings. Invoke the skeptic agent
+   (Task tool, subagent `skeptic`, definition in `.kilo/agent/skeptic.md`)
+   with a prompt such as:
+
+   > Review branch `feat/NNNN-slug` against its spec `specs/NNNN-slug.md`
+   > (diff base: `master`). Follow the checklist in
+   > `.kilo/agent/skeptic.md` and answer in the verdict format
+   > (`BLOCKING: ...` / `NITS: ...` / `APPROVED`).
+
+`BLOCKING` findings forbid the merge; fix and re-review.
+
+## 8. Secrets and safety
+
+- Your own device and account data are confidential: never include them in
+  this public repository — in code, docs, examples, fixtures, or commit
+  history. This covers lock serial numbers, device addresses, key material,
+  and account data (usernames, passwords, tokens). Use synthetic
+  placeholders (`<serial>`, `<username>`); real values live only in
+  environment variables or gitignored `*.local.json` files.
+- Never log tokens, keys, or Authorization headers; tests must verify log
+  redaction where logging is involved.
+
+## 9. Publication policy (public repository)
+
+- Do not copy text or material from non-public sources into this repo.
+- Public documentation is an English description of API behavior. Cite only
+  this repository's own specs; do not name non-public or third-party sources,
+  and do not state or claim how the API was determined.
+- Everything in this repo is English (§2); keep the disclaimers in place
+  (unofficial, not affiliated with Danalock AS, own devices only).
+
+## 10. References
+
+- Specs: `specs/` (0001 OAuth2 authentication is the first deliverable).
+- Group contract: `DeviceKey` (specs 0002/0003).
+- Python >= 3.11; versioning: SemVer, 0.x while the API is unstable.

pydanalock_cloud-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The pydanalock-cloud contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pydanalock_cloud-0.5.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.5
+Name: pydanalock-cloud
+Version: 0.5.0
+Summary: Unofficial Python client for the Danalock cloud API (OAuth2, devices, keys)
+Project-URL: Homepage, https://github.com/buggy-shep/pydanalock-cloud
+Project-URL: Repository, https://github.com/buggy-shep/pydanalock-cloud
+Project-URL: Issues, https://github.com/buggy-shep/pydanalock-cloud/issues
+Project-URL: Changelog, https://github.com/buggy-shep/pydanalock-cloud/releases
+Author: The pydanalock-cloud contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cloud,danalock,home-automation,oauth2,smart-lock
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.28
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: release
+Requires-Dist: build>=1.2; extra == 'release'
+Requires-Dist: twine>=5; extra == 'release'
+Description-Content-Type: text/markdown
+
+# pydanalock-cloud
+
+[![PyPI version](https://img.shields.io/pypi/v/pydanalock-cloud.svg)](https://pypi.org/project/pydanalock-cloud/)
+[![CI](https://github.com/buggy-shep/pydanalock-cloud/actions/workflows/ci.yml/badge.svg)](https://github.com/buggy-shep/pydanalock-cloud/actions/workflows/ci.yml)
+
+Unofficial Python client for the Danalock cloud API: OAuth2 authentication,
+device listing, and retrieval of the per-device key material (login token
+blob, broadcast key) used by BLE clients such as
+[pydanalock-ble](https://github.com/buggy-shep/pydanalock-ble).
+
+> **Disclaimer.** This project is unofficial and is not affiliated with,
+> endorsed by, or sponsored by Danalock AS or Poly-Control. It is built for
+> interoperability with devices you own. Use it at your own risk; only control
+> devices you are authorized to control.
+
+## Install
+
+```bash
+pip install pydanalock-cloud
+```
+
+## Status
+
+OAuth2 authentication, device/key retrieval, forced key refresh, client
+lifecycle, and latest firmware lookup are implemented (specs 0001–0006);
+0.x — the API may still change. See [`specs/`](specs/) for the
+specifications and their status.
+
+Capabilities:
+
+- OAuth2 authentication (refresh + password grants) with pluggable token
+  storage — [spec 0001](specs/0001-oauth2-auth.md)
+- Device listing and key retrieval with automatic refresh —
+  [spec 0002](specs/0002-devices-keys.md)
+- Public sync + async client API (`DanalockCloud`, `AsyncDanalockCloud`,
+  `DeviceKey`) — [spec 0003](specs/0003-client-api.md)
+- Client lifecycle close methods — [spec 0004](specs/0004-client-lifecycle.md)
+- Forced key refetch (`get_key(..., force=True)`) —
+  [spec 0005](specs/0005-key-refetch-force.md)
+- Latest firmware lookup (unauthenticated firmware service; the download
+  URL in the result is a short-lived signed link and must not be
+  persisted) — [spec 0006](specs/0006-firmware-latest.md)
+
+## Requirements
+
+- Python >= 3.11
+- [httpx](https://pypi.org/project/httpx/) >= 0.28
+
+## Development
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+.venv/bin/ruff check .
+.venv/bin/ruff format --check .
+.venv/bin/mypy
+.venv/bin/pytest -m "not live"
+```
+
+Live tests against the production API stay behind the `live` marker and are
+run manually only, with credentials from the environment
+(`DANALOCK_USERNAME`, `DANALOCK_PASSWORD`).
+
+## License
+
+[MIT](LICENSE)

pydanalock_cloud-0.5.0/README.md

@@ -0,0 +1,66 @@
+# pydanalock-cloud
+
+[![PyPI version](https://img.shields.io/pypi/v/pydanalock-cloud.svg)](https://pypi.org/project/pydanalock-cloud/)
+[![CI](https://github.com/buggy-shep/pydanalock-cloud/actions/workflows/ci.yml/badge.svg)](https://github.com/buggy-shep/pydanalock-cloud/actions/workflows/ci.yml)
+
+Unofficial Python client for the Danalock cloud API: OAuth2 authentication,
+device listing, and retrieval of the per-device key material (login token
+blob, broadcast key) used by BLE clients such as
+[pydanalock-ble](https://github.com/buggy-shep/pydanalock-ble).
+
+> **Disclaimer.** This project is unofficial and is not affiliated with,
+> endorsed by, or sponsored by Danalock AS or Poly-Control. It is built for
+> interoperability with devices you own. Use it at your own risk; only control
+> devices you are authorized to control.
+
+## Install
+
+```bash
+pip install pydanalock-cloud
+```
+
+## Status
+
+OAuth2 authentication, device/key retrieval, forced key refresh, client
+lifecycle, and latest firmware lookup are implemented (specs 0001–0006);
+0.x — the API may still change. See [`specs/`](specs/) for the
+specifications and their status.
+
+Capabilities:
+
+- OAuth2 authentication (refresh + password grants) with pluggable token
+  storage — [spec 0001](specs/0001-oauth2-auth.md)
+- Device listing and key retrieval with automatic refresh —
+  [spec 0002](specs/0002-devices-keys.md)
+- Public sync + async client API (`DanalockCloud`, `AsyncDanalockCloud`,
+  `DeviceKey`) — [spec 0003](specs/0003-client-api.md)
+- Client lifecycle close methods — [spec 0004](specs/0004-client-lifecycle.md)
+- Forced key refetch (`get_key(..., force=True)`) —
+  [spec 0005](specs/0005-key-refetch-force.md)
+- Latest firmware lookup (unauthenticated firmware service; the download
+  URL in the result is a short-lived signed link and must not be
+  persisted) — [spec 0006](specs/0006-firmware-latest.md)
+
+## Requirements
+
+- Python >= 3.11
+- [httpx](https://pypi.org/project/httpx/) >= 0.28
+
+## Development
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+.venv/bin/ruff check .
+.venv/bin/ruff format --check .
+.venv/bin/mypy
+.venv/bin/pytest -m "not live"
+```
+
+Live tests against the production API stay behind the `live` marker and are
+run manually only, with credentials from the environment
+(`DANALOCK_USERNAME`, `DANALOCK_PASSWORD`).
+
+## License
+
+[MIT](LICENSE)

pydanalock_cloud-0.5.0/pyproject.toml

@@ -0,0 +1,75 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pydanalock-cloud"
+version = "0.5.0"
+description = "Unofficial Python client for the Danalock cloud API (OAuth2, devices, keys)"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{ name = "The pydanalock-cloud contributors" }]
+keywords = ["danalock", "cloud", "oauth2", "smart-lock", "home-automation"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Home Automation",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.28",
+]
+
+[project.urls]
+Homepage = "https://github.com/buggy-shep/pydanalock-cloud"
+Repository = "https://github.com/buggy-shep/pydanalock-cloud"
+Issues = "https://github.com/buggy-shep/pydanalock-cloud/issues"
+Changelog = "https://github.com/buggy-shep/pydanalock-cloud/releases"
+
+[project.optional-dependencies]
+dev = [
+    "mypy>=1.11",
+    "pytest>=8.2",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.6",
+]
+release = [
+    "build>=1.2",
+    "twine>=5",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pydanalock"]
+
+[tool.hatch.build.targets.sdist]
+exclude = [".kilo"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-m 'not live'"
+asyncio_mode = "auto"
+markers = [
+    "live: talks to a real lock or the real cloud; run manually only",
+]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+files = ["src"]
+mypy_path = "src"
+explicit_package_bases = true
+namespace_packages = true
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["B", "E", "F", "I", "RUF", "SIM", "UP", "W"]

pydanalock_cloud-0.5.0/specs/0001-oauth2-auth.md

@@ -0,0 +1,107 @@
+# 0001 — OAuth2 authentication
+
+- **Status:** implemented
+- **Scope:** `pydanalock.cloud` authentication against the Danalock cloud API
+
+## Summary
+
+The Danalock cloud (base URL `https://api.danalock.com`) issues OAuth2
+tokens. This spec defines the token flows the client supports, token storage,
+and automatic refresh.
+
+## Motivation
+
+Every device/keys endpoint requires a bearer access token; keys are the
+contract payload shared with the BLE library, so authentication is the cloud
+client's first deliverable.
+
+## Requirements
+
+- R1 (MUST) Token endpoint: `POST /oauth2/token`,
+  `application/x-www-form-urlencoded`. Supported grants:
+  - `refresh_token` — used automatically;
+  - `password` (resource-owner password credentials) — fallback for scripted
+    or hosted use; requires username and password.
+
+  The `authorization_code` grant is deferred to a future spec (recorded
+  decision, 2026-09-06): obtaining the code requires a browser redirect
+  owned by the host application, which no current consumer drives.
+- R2 (MUST) `client_id` is required for every grant; the library default is
+  `danalock-android` (a value observed working against the production API);
+  it is configurable.
+- R3 (MUST) Token response fields used: `access_token`, `refresh_token`,
+  `expires_in`. The client computes `expires_at` locally (epoch seconds).
+- R4 (MUST) Automatic refresh: a 401 response, or a token expiring within a
+  60-second safety margin, triggers one `refresh_token` grant and one retry
+  of the original request. Refresh failure surfaces as `AuthError`.
+- R5 (MUST) Token storage is pluggable:
+
+```python
+class TokenStorage(Protocol):
+    def load(self) -> TokenData | None: ...
+    def save(self, token: TokenData) -> None: ...
+    def clear(self) -> None: ...
+```
+
+  An in-memory implementation MUST be provided; host applications supply
+  persistent ones. Tokens and credentials MUST NOT be logged or committed.
+- R6 (MUST) Typed errors: `AuthError` (invalid credentials/grant), `ApiError`
+  (unexpected HTTP status), transport errors propagated from httpx.
+- R7 (SHOULD) All requests set `Accept: application/json` and use a
+  configurable timeout (default 30 seconds).
+
+## Design
+
+- One httpx client instance per `DanalockCloud`; the base URL and transport
+  are overridable for tests (MockTransport).
+- The password grant exists because the authorization-code flow needs a
+  browser/redirect endpoint that standalone scripts and servers do not have.
+
+## API
+
+```python
+@dataclass(frozen=True)
+class TokenData:
+    access_token: str
+    refresh_token: str
+    expires_at: float  # epoch seconds
+
+
+class DanalockCloud:
+    def __init__(
+        self,
+        *,
+        client_id: str = "danalock-android",
+        base_url: str = "https://api.danalock.com",
+        storage: TokenStorage | None = None,
+    ) -> None: ...
+    def login_password(self, username: str, password: str) -> None: ...
+    def refresh(self) -> None: ...
+    def access_token(self) -> str: ...  # valid token, refreshing as needed
+```
+
+(Async variants are defined in spec 0003.)
+
+## Test plan
+
+- httpx MockTransport fixtures: successful password grant; refresh grant;
+  401 → refresh → retry; refresh failure → `AuthError`; storage save/load.
+- Expired-token margin: a token within the 60-second margin triggers refresh
+  before the request.
+- No secrets in logged output (test asserts redaction).
+
+## Acceptance criteria
+
+- Unit tests green (mock transport); gate green; skeptic without `BLOCKING`.
+- Live (manual, `live` marker): password login against the production API
+  succeeds with real credentials from environment variables.
+
+## Out of scope
+
+- Authorization-code grant and its redirect UI (deferred to a future spec;
+  see R1); key retrieval (spec 0002); public API surface (spec 0003).
+
+## Status
+
+`implemented` (2026-09-06: password-grant authentication with token
+storage, refresh and expiry tracking merged, version 0.1.0).