chore: initial commit

2026-06-25 00:34:34 +08:00
commit 3cce1be162
295 changed files with 30971 additions and 0 deletions
@@ -0,0 +1,36 @@
+/*
+ * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include <stdbool.h>
+#include <stddef.h>
+#include "esp_err.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define CONTROL_PLANE_MULTIMODAL_AUTH_TOKEN_MAX_LEN 256
+#define CONTROL_PLANE_MULTIMODAL_AUTH_ID_MAX_LEN 64
+#define CONTROL_PLANE_MULTIMODAL_AUTH_VOICE_MAX_LEN 64
+
+typedef struct {
+    char token[CONTROL_PLANE_MULTIMODAL_AUTH_TOKEN_MAX_LEN];
+    char workspace_id[CONTROL_PLANE_MULTIMODAL_AUTH_ID_MAX_LEN];
+    char app_id[CONTROL_PLANE_MULTIMODAL_AUTH_ID_MAX_LEN];
+    char voice_id[CONTROL_PLANE_MULTIMODAL_AUTH_VOICE_MAX_LEN];
+    char device_id[CONTROL_PLANE_MULTIMODAL_AUTH_ID_MAX_LEN];
+    char serial_number[CONTROL_PLANE_MULTIMODAL_AUTH_ID_MAX_LEN];
+    bool valid;
+} control_plane_multimodal_auth_info_t;
+
+esp_err_t control_plane_multimodal_auth_fetch(control_plane_multimodal_auth_info_t *out);
+void control_plane_multimodal_auth_clear(void);
+
+#ifdef __cplusplus
+}
+#endif
@@ -0,0 +1,120 @@
+/*
+ * SPDX-FileCopyrightText: 2024-2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+
+#include "esp_err.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*
+ * Device-auth (device-JWT) engine, control-plane internal.
+ *
+ * The device proves possession of an on-board P-256 key via a challenge/response
+ * signature against the registration backend and is issued a short-lived device
+ * JWT. That JWT is used as the Bearer when requesting the per-session multimodal
+ * token. Persistence (key material + JWT state) is delegated to the platform
+ * store through the domain facade; this engine owns the crypto, HTTP, and the
+ * JWT lifecycle/state machine.
+ */
+
+#define CONTROL_PLANE_DEVICE_AUTH_SCOPE_VOICE_SESSION (1u << 0)
+#define CONTROL_PLANE_DEVICE_AUTH_SCOPE_OTA_REPORT    (1u << 1)
+#define CONTROL_PLANE_DEVICE_AUTH_SCOPE_OTA_READ      (1u << 2)
+#define CONTROL_PLANE_DEVICE_AUTH_SCOPE_OTA_CONFIRM   (1u << 3)
+#define CONTROL_PLANE_DEVICE_AUTH_SCOPE_ALL                       \
+    (CONTROL_PLANE_DEVICE_AUTH_SCOPE_VOICE_SESSION |              \
+     CONTROL_PLANE_DEVICE_AUTH_SCOPE_OTA_REPORT |                 \
+     CONTROL_PLANE_DEVICE_AUTH_SCOPE_OTA_READ |                   \
+     CONTROL_PLANE_DEVICE_AUTH_SCOPE_OTA_CONFIRM)
+
+#define CONTROL_PLANE_DEVICE_AUTH_JWT_MAX_LEN 1536
+
+typedef enum {
+    CONTROL_PLANE_DEVICE_AUTH_OK = 0,
+    CONTROL_PLANE_DEVICE_AUTH_WAIT_FACTORY,
+    CONTROL_PLANE_DEVICE_AUTH_RETRY_LATER,
+    CONTROL_PLANE_DEVICE_AUTH_FATAL,
+} control_plane_device_auth_result_t;
+
+/**
+ * @brief Initialize the engine: load persisted key material + JWT state.
+ *
+ * Idempotent and safe to call repeatedly. Returns `ESP_OK` once key material is
+ * available (loaded or freshly generated); returns an error only when the key
+ * store is unusable.
+ */
+esp_err_t control_plane_multimodal_device_auth_init(void);
+
+/**
+ * @brief Ensure a valid device JWT exists for the requested scope.
+ *
+ * Runs challenge/response (and server-driven key rotation) as needed, applying
+ * retry/backoff. `force_refresh` bypasses the cached JWT.
+ */
+control_plane_device_auth_result_t control_plane_multimodal_device_auth_ensure(
+        uint32_t required_scope_mask,
+        bool force_refresh);
+
+/**
+ * @brief Copy the current device JWT into @p out.
+ *
+ * Returns `ESP_ERR_NOT_FOUND` when no valid JWT is cached, `ESP_ERR_INVALID_SIZE`
+ * when the buffer is too small, otherwise `ESP_OK`.
+ */
+esp_err_t control_plane_multimodal_device_auth_copy_jwt(char *out, size_t out_len);
+
+/**
+ * @brief Invalidate the cached JWT (e.g. after the token endpoint returns 401/403),
+ *        forcing a fresh challenge/response on the next ensure.
+ */
+void control_plane_multimodal_device_auth_invalidate(int reason);
+
+/*
+ * Factory-provisioning helpers. These expose the device's key material and sign
+ * factory challenges/rotations during manufacturing/registration. They only need
+ * the on-board key (loaded or generated), so they work independently of whether
+ * the AUTH_V2 token flow is enabled at runtime.
+ */
+
+/** @brief Return the device public key + JKT thumbprint (base64url) and key version. */
+esp_err_t control_plane_multimodal_device_auth_get_key_material(char *out_pub_key_b64u,
+                                                                size_t pub_key_b64u_len,
+                                                                char *out_pub_key_jkt_b64u,
+                                                                size_t pub_key_jkt_b64u_len,
+                                                                uint32_t *out_key_version);
+
+/** @brief Sign a factory challenge with the device key (raw r||s, base64url). */
+esp_err_t control_plane_multimodal_device_auth_sign_challenge(const char *device_id,
+                                                              const char *challenge_id_b64u,
+                                                              const char *challenge_b64u,
+                                                              char *out_signature_b64u,
+                                                              size_t out_signature_b64u_len);
+
+/**
+ * @brief Generate and sign a rotation to a new key. When @p apply_local_key is
+ *        true the new key is persisted locally (key_version+1) and the cached JWT
+ *        is invalidated.
+ */
+esp_err_t control_plane_multimodal_device_auth_prepare_rotate(const char *device_id,
+                                                              uint32_t key_version,
+                                                              char *out_new_pub_key_b64u,
+                                                              size_t new_pub_key_b64u_len,
+                                                              char *out_new_pub_key_jkt_b64u,
+                                                              size_t new_pub_key_jkt_b64u_len,
+                                                              char *out_signature_b64u,
+                                                              size_t out_signature_b64u_len,
+                                                              bool apply_local_key);
+
+#ifdef __cplusplus
+}
+#endif