tfaour/espresso_frame
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases 13 Wiki Activity

Redesign phase C: claim flow, limited manage page, device protocol

Browse Source 
The frame-claiming pipeline, end to end. Firmware: every request now
carries ?id=<12-hex STA MAC> via build_url (mirrored in build_ota_url),
and the captive portal's success page became a redirect that hands the
user's browser to <server>/claim?device_id=... after ~7s -- enough time
for the phone to drop the provisioning AP while the device reboots.
The server pushes a per-frame device token through /frame/config during
a one-time handshake; the firmware persists it to NVS (a dedicated
single-key write that deliberately doesn't reset the connected-once
flag or WiFi cache) and prefers it over the provisioned shared token
from the next request on. Config response buffer grows 256->512. Both
board variants compile clean; new firmware also works against an old
server (which ignores ?id=) and old firmware against this server (the
phase A legacy mapping), so either deploy order survives.

Server: /claim lands the captive-portal redirect -- claim-gated signup
(a valid unclaimed/unregistered device id IS the enrollment invitation),
pending claims for the user-beats-the-frame race (auto-attached at
self-registration, 24h expiry), and a waiting page that refreshes until
the frame checks in. Unclaimed/unconfigured frames get a rendered
instruction placeholder with a QR from /frame/image (200, never an
error loop) -- new qrcode dep, placeholder shares the exact
quantize/pack path photos use.

The on-frame manage QR now resolves to a limited no-login page: scans
of / carrying device credentials (new ?id&token or the legacy shared
token) 303 to /m/<manage_token>, which allows exactly view queue,
show-next, advance, back, and scoped thumbnails -- no settings, no
removal, no other frames. Full control means logging in.

One real protocol hole found by simulating full wake cycles: after
self-registration the device could never authenticate again (the wake
cycle fetches the image BEFORE /frame/config delivers its token).
require_device now treats the id itself as the credential until the
first authenticated request flips device_token_ack -- the same trust
level as open registration, closing permanently once the handshake
completes.
This commit is contained in:
tfaour
2026-07-21 23:44:22 -04:00
parent 1e8d6803ac
commit 683e3881b1
15 changed files with 779 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files
firmware/main/frame_client.c
+43 -8
View File
@@ -99,11 +99,14 @@ static void save_wifi_cache(esp_netif_t *netif)
* normally a bare "host:port", defaulting to plain http; it may instead
* carry an explicit "http://" or "https://" prefix to pick the scheme,
* e.g. "https://frame.example.com" if a reverse proxy is terminating
* TLS in front of the tools server. The token, once the server has
* MANAGEMENT_TOKEN set, is required on every request the server
* receives (device-facing endpoints included, not just the web UI) --
* this is the one chokepoint all of them go through, so every caller
* gets it for free instead of needing to remember to add it. */
* TLS in front of the tools server. Every URL carries ?id= (the device's
* MAC-derived identity -- how a multi-frame server tells frames apart
* and how an unknown frame self-registers) plus &token=: the server-
* issued per-frame device token once one has been delivered via
* /frame/config, else the provisioned access token (the legacy shared
* secret, also what a pre-multi-frame server still expects). This is
* the one chokepoint all requests go through, so every caller gets both
* for free instead of needing to remember to add them. */
static void build_url(char *out, size_t out_size, const frame_config_t *cfg, const char *path)
{
const char *toolsserver = cfg->toolsserver;
@@ -113,8 +116,16 @@ static void build_url(char *out, size_t out_size, const frame_config_t *cfg, con
} else {
len = (size_t)snprintf(out, out_size, "http://%s/%s", toolsserver, path);
}
if (cfg->access_token[0] != '\0' && len < out_size) {
snprintf(out + len, out_size - len, "?token=%s", cfg->access_token);
char device_id[FRAME_DEVICE_ID_LEN + 1];
frame_device_id_get(device_id, sizeof(device_id));
if (len < out_size) {
len += (size_t)snprintf(out + len, out_size - len, "?id=%s", device_id);
}
const char *token = cfg->device_token[0] != '\0' ? cfg->device_token : cfg->access_token;
if (token[0] != '\0' && len < out_size) {
snprintf(out + len, out_size - len, "&token=%s", token);
}
}
@@ -266,6 +277,11 @@ typedef struct {
bool reachable;
uint32_t refresh_interval_s; /* CONFIG_FRAME_SLEEP_INTERVAL_S if absent/unparseable */
char firmware_version[32]; /* server's uploaded OTA image version; empty if none/unreachable */
/* Per-frame token the server pushes until this device has
* authenticated with it once; empty when absent. Persisted via
* frame_config_set_device_token() and used by build_url() from the
* next request on. */
char device_token[FRAME_CFG_TOKEN_MAX_LEN + 1];
} frame_server_config_t;
/* Finds the first integer value associated with "key" in a small JSON
@@ -356,6 +372,7 @@ static frame_server_config_t fetch_frame_config(const frame_config_t *cfg)
.refresh_interval_s = CONFIG_FRAME_SLEEP_INTERVAL_S,
};
result.firmware_version[0] = '\0';
result.device_token[0] = '\0';
char url[256];
build_url(url, sizeof(url), cfg, "frame/config");
@@ -380,7 +397,10 @@ static frame_server_config_t fetch_frame_config(const frame_config_t *cfg)
esp_http_client_fetch_headers(client);
result.reachable = true;
char body[256];
/* 512 (was 256): the response also carries "device_token" during the
* one-time identity handshake -- worst case is still well under half
* of this, the rest is headroom for future fields. */
char body[512];
int total = 0;
int n;
while (total < (int)sizeof(body) - 1 &&
@@ -400,6 +420,7 @@ static frame_server_config_t fetch_frame_config(const frame_config_t *cfg)
(int)result.refresh_interval_s);
}
json_extract_string(body, "firmware_version", result.firmware_version, sizeof(result.firmware_version));
json_extract_string(body, "device_token", result.device_token, sizeof(result.device_token));
return result;
}
@@ -952,6 +973,20 @@ void frame_client_run(const frame_config_t *cfg, fetch_action_t action, bool sho
frame_server_config_t server_cfg = fetch_frame_config(cfg);
sleep_seconds = server_cfg.reachable ? server_cfg.refresh_interval_s : CONFIG_FRAME_RETRY_INTERVAL_S;
/* One-time identity handshake: the server pushes this frame's
* own token until we've authenticated with it once. Persist it
* and use it immediately (the OTA below is part of this same
* cycle) via a local working copy -- cfg itself is const. */
frame_config_t updated_cfg;
if (server_cfg.device_token[0] != '\0' &&
strcmp(server_cfg.device_token, cfg->device_token) != 0) {
frame_config_set_device_token(server_cfg.device_token);
updated_cfg = *cfg;
snprintf(updated_cfg.device_token, sizeof(updated_cfg.device_token), "%s",
server_cfg.device_token);
cfg = &updated_cfg;
}
/* Last, deliberately -- the photo's already on screen and the
* battery report already sent, so a reboot here (whether OTA
* succeeds or the device is mid-update) never loses either. */
firmware/main/ota_update.c
+11 -3
View File
@@ -17,7 +17,7 @@ static const char *TAG = "ota_update";
#define OTA_HTTP_TIMEOUT_MS 30000
/* Built the same way as every other tools-server URL -- scheme/cert/
* token handling all come from build_url()'s conventions. Duplicated
* id/token handling all come from build_url()'s conventions. Duplicated
* tiny helper rather than exporting frame_client.c's static build_url();
* kept byte-identical in behavior (see frame_client.c). */
static void build_ota_url(char *out, size_t out_size, const frame_config_t *cfg)
@@ -29,8 +29,16 @@ static void build_ota_url(char *out, size_t out_size, const frame_config_t *cfg)
} else {
len = (size_t)snprintf(out, out_size, "http://%s/frame/firmware", toolsserver);
}
if (cfg->access_token[0] != '\0' && len < out_size) {
snprintf(out + len, out_size - len, "?token=%s", cfg->access_token);
char device_id[FRAME_DEVICE_ID_LEN + 1];
frame_device_id_get(device_id, sizeof(device_id));
if (len < out_size) {
len += (size_t)snprintf(out + len, out_size - len, "?id=%s", device_id);
}
const char *token = cfg->device_token[0] != '\0' ? cfg->device_token : cfg->access_token;
if (token[0] != '\0' && len < out_size) {
snprintf(out + len, out_size - len, "&token=%s", token);
}
}
firmware/main/root.html
+6 -2
View File
@@ -98,10 +98,14 @@
</div>
<div class="input-group">
<label for="access_token">Access Token (optional)</label>
<input type="text" id="access_token" name="access_token" placeholder="only if the server's MANAGEMENT_TOKEN is set" maxlength="64">
<label for="access_token">Access Token (optional &mdash; only for older servers)</label>
<input type="text" id="access_token" name="access_token" placeholder="usually blank; current servers issue one automatically" maxlength="64">
</div>
<p style="font-size: 13px; color: #555;">After saving, this page will
take you to the server to claim your frame &mdash; reconnect to
your normal WiFi if it doesn't happen automatically.</p>
<button type="submit">Submit</button>
</form>
firmware/main/wifi_provisioning.c
+63 -2
View File
@@ -83,10 +83,39 @@ esp_err_t frame_config_load(frame_config_t *out)
return token_err;
}
/* Optional: absent until the server has pushed a per-frame token
* (see frame_config_set_device_token). */
len = sizeof(out->device_token);
token_err = nvs_get_str(handle, "device_token", out->device_token, &len);
if (token_err != ESP_OK && token_err != ESP_ERR_NVS_NOT_FOUND) {
nvs_close(handle);
return token_err;
}
nvs_close(handle);
return ESP_OK;
}
void frame_device_id_get(char *out, size_t out_size)
{
uint8_t mac[6] = {0};
ESP_ERROR_CHECK(esp_read_mac(mac, ESP_MAC_WIFI_STA));
snprintf(out, out_size, "%02x%02x%02x%02x%02x%02x",
mac[0], mac[1], mac[2], mac[3], mac[4], mac[5]);
}
void frame_config_set_device_token(const char *token)
{
nvs_handle_t handle;
if (nvs_open(NVS_NAMESPACE, NVS_READWRITE, &handle) != ESP_OK) {
return;
}
nvs_set_str(handle, "device_token", token);
nvs_commit(handle);
nvs_close(handle);
ESP_LOGI(TAG, "Stored server-issued device token");
}
esp_err_t frame_config_save(const frame_config_t *cfg)
{
nvs_handle_t handle;
@@ -106,6 +135,10 @@ esp_err_t frame_config_save(const frame_config_t *cfg)
err = nvs_set_str(handle, "access_token", cfg->access_token);
}
if (err == ESP_OK) {
/* Re-provisioning restarts the identity handshake: the server
* (possibly a different one now) re-issues a device token when
* the frame next introduces itself. */
nvs_erase_key(handle, "device_token");
/* Fresh (re)provisioning -- the next successful connection should
* show the status screen again. */
err = nvs_set_u8(handle, "connected_once", 0);
@@ -159,6 +192,7 @@ void frame_config_clear(void)
nvs_erase_key(handle, "sta_pass");
nvs_erase_key(handle, "toolsserver");
nvs_erase_key(handle, "access_token");
nvs_erase_key(handle, "device_token");
nvs_erase_key(handle, "connected_once");
nvs_commit(handle);
nvs_close(handle);
@@ -412,8 +446,35 @@ static esp_err_t save_config_post_handler(httpd_req_t *req)
ESP_LOGI(TAG, "Saved config: ssid='%s' toolsserver='%s' access_token=%s", cfg.sta_ssid, cfg.toolsserver,
strlen(cfg.access_token) ? "set" : "none");
static const char resp[] =
"<html><body><h3>Saved. Restarting and connecting to your WiFi...</h3></body></html>";
/* The success page hands the browser off to the server's claim page,
* carrying this device's id -- how a frame gets linked to a user
* account. The ~7s delay covers the phone dropping this softAP (the
* device reboots right after this response) and rejoining its normal
* WiFi before the redirect fires; the visible link is the fallback
* if the phone loses that race. Scheme handling matches
* frame_client.c's build_url(): a bare host gets http://. */
char device_id[FRAME_DEVICE_ID_LEN + 1];
frame_device_id_get(device_id, sizeof(device_id));
char claim_url[FRAME_CFG_SERVER_MAX_LEN + 64];
const char *scheme = "";
if (strncmp(cfg.toolsserver, "http://", 7) != 0 && strncmp(cfg.toolsserver, "https://", 8) != 0) {
scheme = "http://";
}
snprintf(claim_url, sizeof(claim_url), "%s%s/claim?device_id=%s", scheme, cfg.toolsserver, device_id);
char resp[1024];
snprintf(resp, sizeof(resp),
"<!doctype html><html><head>"
"<meta http-equiv=\"refresh\" content=\"7;url=%s\">"
"<style>body{font-family:sans-serif;text-align:center;padding:2em}</style></head>"
"<body><h3>Saved &mdash; the frame is restarting</h3>"
"<p>Reconnect to your normal WiFi. You'll be taken to the claim page "
"in a few seconds&hellip;</p>"
"<p><a href=\"%s\">Continue to claim your frame</a></p>"
"<script>setTimeout(function(){location.href=%c%s%c},7000)</script>"
"</body></html>",
claim_url, claim_url, '"', claim_url, '"');
httpd_resp_set_type(req, "text/html");
httpd_resp_send(req, resp, HTTPD_RESP_USE_STRLEN);
firmware/main/wifi_provisioning.h
+25 -1
View File
@@ -11,13 +11,37 @@
#define FRAME_CFG_TOKEN_MAX_LEN 64
#define FRAME_AP_PASSWORD_LEN 10
#define FRAME_DEVICE_ID_LEN 12 /* 6-byte STA MAC as lowercase hex */
typedef struct {
char sta_ssid[FRAME_CFG_SSID_MAX_LEN + 1];
char sta_password[FRAME_CFG_PASSWORD_MAX_LEN + 1];
char toolsserver[FRAME_CFG_SERVER_MAX_LEN + 1];
char access_token[FRAME_CFG_TOKEN_MAX_LEN + 1]; /* optional; matches the server's MANAGEMENT_TOKEN */
char access_token[FRAME_CFG_TOKEN_MAX_LEN + 1]; /* optional; legacy shared MANAGEMENT_TOKEN */
/* Per-frame token issued by the server via GET /frame/config after
* this device first introduces itself by id -- preferred over
* access_token once present (see frame_client.c's build_url). Not
* set at the captive portal; empty until the server pushes one. */
char device_token[FRAME_CFG_TOKEN_MAX_LEN + 1];
} frame_config_t;
/**
* This device's stable identity as reported to the server (?id= on every
* request): the full 6-byte STA MAC as 12 lowercase hex chars. Derived
* from the same MAC the provisioning AP SSID suffix comes from; never
* stored. out must hold at least FRAME_DEVICE_ID_LEN + 1 bytes.
*/
void frame_device_id_get(char *out, size_t out_size);
/**
* Persists (only) the server-issued per-frame device token -- called
* from the wake cycle when GET /frame/config delivers one. Deliberately
* touches nothing else: unlike frame_config_save() it must not reset
* the connected-once flag or invalidate the WiFi fast-connect cache,
* since nothing about the network changed.
*/
void frame_config_set_device_token(const char *token);
/**
* Loads the saved home-network config from NVS.
* Returns ESP_ERR_NVS_NOT_FOUND if the device has never been provisioned.