Prepare Sharp Kitchen for HACS release (blocked on credential architecture)

.github/workflows/hassfest.yml

@@ -0,0 +1,18 @@
+name: Validate with hassfest
+
+on:
+  push:
+  pull_request:
+  schedule:
+    - cron: "0 0 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: home-assistant/actions/hassfest@master

.github/workflows/tests.yml

@@ -0,0 +1,22 @@
+name: Tests
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install test runner
+        run: python -m pip install --upgrade pytest
+      - name: Run release-readiness tests
+        run: python -m pytest -q

.github/workflows/validate-hacs.yml

@@ -0,0 +1,19 @@
+name: Validate with HACS
+
+on:
+  push:
+  pull_request:
+  schedule:
+    - cron: "0 0 * * *"
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  validate-hacs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: HACS validation
+        uses: hacs/action@main
+        with:
+          category: integration

AUTHENTICATION_ARCHITECTURE.md

@@ -0,0 +1,231 @@
+# Authentication Distribution Research
+
+This document records release-blocker research only. It does not change the
+working authentication implementation.
+
+## Current blocker
+
+The working integration relies on application authentication material recovered
+from the official Sharp Kitchen application, including a Cognito application
+client credential and a shared mTLS client certificate/private key. The formal
+HACS release must not embed the extracted private key.
+
+## Options under consideration
+
+### 1. User-provided Sharp application credential + user-provided mTLS PEM files
+
+Home Assistant can store user-entered OAuth client ID/client secret values
+through its Application Credentials framework. The mTLS certificate/private key
+would still need a separate mechanism, such as paths under the Home Assistant
+configuration directory or values entered during a setup/reconfigure flow.
+
+Pros:
+- public repository contains no extracted private key;
+- no hosted relay service;
+- closest to normal local secret management.
+
+Cons:
+- ordinary Sharp users do not appear to have a supported developer portal for
+  creating their own Sharp Kitchen OAuth client;
+- obtaining the same vendor-app credentials and mTLS private key currently
+  requires reverse-engineering/extraction work and is not a realistic normal
+  installation experience.
+
+### 2. User-supplied credential bundle produced by a separate extraction helper
+
+Keep extracted credential material out of the HACS repository. A separate tool
+could produce a local bundle that the integration imports.
+
+Pros:
+- HACS repository remains credential-free;
+- integration setup could validate the bundle before saving paths/material.
+
+Cons:
+- extraction of the mTLS private key remains technically difficult;
+- the current research indicates the app's bundled PKCS#12 material is not a
+  simple user-exportable credential;
+- adds a substantial prerequisite and support burden.
+
+### 3. Supported Sharp provisioning/pairing flow that generates per-installation mTLS credentials
+
+This is the preferred architecture if Sharp exposes such a flow.
+
+Pros:
+- cleanest security model;
+- no shared private key distribution;
+- comparable to integrations that pair and generate/store a unique client
+  certificate for each Home Assistant installation.
+
+Cons:
+- no such Sharp provisioning endpoint has been identified yet;
+- requires further protocol research before it can be considered viable.
+
+### 4. User-provided certificate/key files obtained independently
+
+The integration would accept certificate and private-key paths or pasted PEM
+material, but would not prescribe or automate extraction.
+
+Pros:
+- technically straightforward for the Home Assistant integration;
+- public repository stays free of the private key.
+
+Cons:
+- poor user experience;
+- most users cannot realistically obtain the material;
+- support/documentation would still need to address how legitimate users obtain
+  it.
+
+### 5. Project-operated relay/proxy service holding the shared mTLS key
+
+Home Assistant would authenticate users locally, but Sharp API calls requiring
+mTLS would transit a service controlled by the project.
+
+Pros:
+- HACS package contains no Sharp private key;
+- easiest end-user setup.
+
+Cons:
+- creates a new hosted service, operating cost, privacy/security responsibility,
+  availability dependency, and trust boundary;
+- routes appliance/account traffic through a third party;
+- not recommended for this project unless all direct-client approaches fail.
+
+## Home Assistant Application Credentials
+
+Application Credentials is suitable for storing/selecting a user-provided
+OAuth client ID and client secret. It does not store or provision a TLS client
+certificate/private key.
+
+Sharp also uses a hosted-login flow tied to the official application's OAuth
+client/redirect behavior. Application Credentials therefore does not, by
+itself, make the current Sharp login flow a standard Home Assistant OAuth flow.
+A separate compatibility investigation is required before refactoring login to
+Home Assistant's OAuth helpers.
+
+## Additional provisioning research
+
+Public Sharp material reviewed during release preparation continues to direct
+SMD2489ES users through the Sharp Kitchen app for appliance pairing. The
+published pairing flow covers Wi-Fi/app/account pairing but does not document
+issuance of a new client TLS certificate or private key to third-party clients.
+
+Sharp also publishes an Alexa account-linking path using the user's Sharp
+account. This proves that Sharp supports account linking outside the mobile app,
+but it does not expose a public device-control API, a user-created OAuth client,
+or a per-installation mTLS credential flow that Home Assistant could currently
+reuse.
+
+Public GitHub/code searches for the Sharp Kitchen backend host, API path,
+application package, and bundled PKCS#12 filename did not uncover an independent
+implementation or a documented certificate-registration endpoint.
+
+## 2026 SHARP HOME migration findings
+
+Sharp introduced a newer **SHARP HOME** app in 2025. Current 2026 Sharp pairing
+documentation distinguishes appliance revisions by model suffix rather than
+migrating every existing SMD2489ES automatically:
+
+- `SMD2489ESF` uses the SHARP HOME app.
+- `SMD2489ESA/B/D/E` use the older Sharp Kitchen app.
+
+The SHARP HOME Android package is `jp.co.sharp.chglobal.na`. Sharp's current
+documentation also shows **SHARP HOME - Kitchen** account linking through Google
+Home and Alexa using a Sharp account, with Google Home relinking required every
+180 days.
+
+This is important because it demonstrates a newer Sharp cloud/account-linking
+stack that supports third-party smart-home ecosystems. However, the public
+documentation does **not** expose:
+
+- a third-party developer API for direct appliance control;
+- a way for Home Assistant users to register their own OAuth application;
+- a method to issue a Home Assistant-specific client TLS certificate/key;
+- evidence that older Sharp Kitchen SMD2489ES revisions can migrate to the
+  SHARP HOME backend.
+
+Therefore the newer SHARP HOME ecosystem is worth separate future protocol
+research, especially for `SMD2489ESF` and later models, but it does not yet
+remove the credential blocker for the existing Sharp Kitchen implementation.
+
+### Best viable public-safe fallback at this checkpoint
+
+If no Sharp provisioning endpoint is discovered, the most practical direct
+client design is:
+
+1. Remove vendor-app secrets/key material from the future public release only
+   after a tested replacement exists.
+2. Let the user supply OAuth application values locally.
+3. Store/select the OAuth client ID and client secret through Home Assistant
+   Application Credentials where compatible with Sharp's hosted-login behavior.
+4. Let the user supply the mTLS certificate and private key as local files,
+   preferably under `/config/sharp_kitchen/`.
+5. Store only file paths/references in the config entry, not private-key text.
+6. Validate certificate/key parsing and matching during setup/reconfigure.
+7. Keep extraction/import outside the HACS package, ideally through a separate
+   local helper if a repeatable extraction method can be made practical.
+
+This is not as user-friendly as true vendor provisioning, but it keeps the HACS
+repository free of the extracted private key and avoids a project-operated
+cloud relay.
+
+## Home Assistant architecture implications
+
+Home Assistant's current Application Credentials framework assumes that users
+can obtain an OAuth client ID and client secret from the provider. It supports
+standard authorization-code flows, PKCE, and custom OAuth implementations, but
+it does not provision or store a TLS client certificate/private key as part of
+that framework.
+
+Home Assistant Cloud Account Linking can provide a smoother OAuth experience
+when the provider cooperates with Nabu Casa, but that would require Sharp to
+support/approve an appropriate OAuth/API integration. It is not something this
+project can manufacture from the existing mobile-app credentials.
+
+The Bosch SHC integration remains the strongest architectural comparison:
+during registration it generates a unique SSL certificate/key pair and
+registers that client with the controller. Sharp's published pairing flow does
+not currently expose an equivalent client-registration step.
+
+### Recommended public-safe design if Sharp offers no provisioning API
+
+The best implementable design with the information currently available is:
+
+1. Keep the public HACS repository free of the extracted shared mTLS private key
+   and vendor-app client secret.
+2. Provide a separate, local-only extraction/import helper that contains no
+   Sharp secret material itself and operates on a user's legitimately obtained
+   app installation/package.
+3. Have that helper write the resulting credential bundle locally under a
+   dedicated Home Assistant configuration directory such as
+   `/config/sharp_kitchen/`.
+4. Have the integration validate and consume the local certificate/key files
+   without copying them into `custom_components`.
+5. Use Home Assistant Application Credentials for client ID/secret only if the
+   Sharp hosted-login implementation can be made compatible and users can
+   realistically obtain/provide those values.
+6. Do not use a project-operated proxy unless direct-client approaches are
+   exhausted, because a proxy creates a new privacy/security/availability
+   dependency.
+
+This approach is less convenient than vendor-supported provisioning, but it is
+the cleanest currently viable way to separate secret distribution from the
+public HACS package while preserving direct communication between Home
+Assistant and Sharp.
+
+## Current recommendation
+
+Do not change the working integration yet.
+
+Research in this order:
+
+1. Determine whether the Sharp backend/app has an undocumented supported
+   registration/provisioning operation capable of issuing a new client
+   certificate/key or otherwise removing the need for the shared app key.
+2. If not, prototype a credential-free public integration that accepts
+   user-supplied client ID/secret and mTLS certificate/key material without
+   committing those values.
+3. Evaluate whether a separate extraction/import helper can make that
+   user-supplied model realistic.
+4. Treat a hosted relay as a last resort.
+
+No release, merge, tag, or HACS submission is authorized by this document.

BRANDING.md

@@ -0,0 +1,37 @@
+# Branding Preparation
+
+Home Assistant 2026.3 and later allows custom integrations to ship branding
+inside `custom_components/sharp_kitchen/brand/`.
+
+## Current approved icon
+
+The user approved a brand-neutral Sharp Kitchen integration icon and it is now
+present on the release-preparation branch at:
+
+`custom_components/sharp_kitchen/brand/icon.png`
+
+The current icon is a square 256×256 PNG created specifically for this
+integration. It shows an original stainless-steel microwave drawer viewed
+straight-on with the drawer slightly open, a subtle warm interior glow, a dark
+navy/charcoal rounded-square background, a black control panel, and a small
+digital display.
+
+The icon intentionally contains:
+
+- no manufacturer logo;
+- no Sharp wordmark;
+- no model number;
+- no Wi-Fi symbol;
+- no product photography;
+- no copied corporate artwork.
+
+The design is intended to remain recognizable at small Home Assistant/HACS icon
+sizes while being completely original and brand-neutral.
+
+## Optional future assets
+
+- `brand/[email protected]` — optional higher-resolution square icon.
+- `brand/logo.png` — optional horizontal logo.
+- Dark-mode variants only if needed for legibility.
+
+Branding preparation does not authorize a release.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aevans0001
+
+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.