From 914e156b62e2f8223888694e75950ca9745719e7 Mon Sep 17 00:00:00 2001 From: ryan Date: Sun, 25 Oct 2026 11:06:51 +0330 Subject: [PATCH] Use only plain characters inside sequence diagram messages GoLand's Mermaid preview renders the flowchart and state diagrams but not two of the sequence diagrams. Remove "|", "||", "+" and braces from message text, the only characters those diagrams had that the others lack. Co-Authored-By: Claude Sonnet 5.5 --- docs/enrollment-and-activation.md | 20 ++++++++++---------- docs/sn-as-username-process.md | 26 +++++++++++++------------- 2 files changed, 23 insertions(+), 23 deletions(-) diff --git a/docs/enrollment-and-activation.md b/docs/enrollment-and-activation.md index ec2b683..d92dd2b 100644 --- a/docs/enrollment-and-activation.md +++ b/docs/enrollment-and-activation.md @@ -46,14 +46,14 @@ sequenceDiagram participant G as Go backend B->>B: random Client ID, X25519 keypair (b, B), nonce n1 B->>M: CONNECT (TLS, anonymous, clientId=random) - B->>G: enroll/request/{cid} {B, n1, mac} + B->>G: enroll/request/[cid] [B, n1, mac] G->>G: create FN record, ephemeral (s, S) G->>G: shared = X25519(s, B), pw = HKDF(shared, FN, n1) G->>M: Dynamic Security: create client FN, pw, role board-bootstrap - G->>B: enroll/response/{cid} {FN, S, sig} (not retained) + G->>B: enroll/response/[cid] [FN, S, sig] (not retained) B->>B: verify sig with pinned public key B->>B: shared = X25519(b, S), same pw - B->>B: persist FN + pw to flash + B->>B: persist FN and pw to flash B->>M: reconnect as FN / pw ``` @@ -94,13 +94,13 @@ sequenceDiagram participant G as Go backend participant M as Mosquitto participant B as Board (FN) - B->>G: board/{FN}/activation/request + B->>G: board/[FN]/activation/request O->>G: pick SN, confirm code and short string - G->>M: ensure role machine-{SN} (literal ACLs device/{SN}/...) - G->>M: add roles machine-{SN} + capability roles to client FN - G->>B: board/{FN}/activation/response {SN, sig} + G->>M: ensure role machine-[SN] (literal ACLs device/[SN]/...) + G->>M: add roles machine-[SN] + capability roles to client FN + G->>B: board/[FN]/activation/response [SN, sig] B->>B: store SN, reconnect as FN - B->>M: use device/{SN}/... topics + B->>M: use device/[SN]/... topics ``` - **Roles:** one assignment role per machine, `machine-`, with **literal** topics such as `device/SN000123/sales/report`. `%u` cannot express the SN here because the username is the FN. Plus shared capability roles (`vending`, `news`, `updates`). @@ -119,12 +119,12 @@ sequenceDiagram participant M as Mosquitto participant B as Board (FN) B->>B: new ephemeral X25519 keypair (b2, B2) - B->>G: board/{FN}/activation/request {B2, n2} + B->>G: board/[FN]/activation/request [B2, n2] O->>G: pick SN, confirm code and short string G->>G: ephemeral (s2, S2), shared = X25519(s2, B2) G->>G: pw = HKDF(shared, SN, n2, generation) G->>M: create or update client SN: pw, clientId bound to board, role vending-device - G->>B: board/{FN}/activation/response {SN, S2, sig} + G->>B: board/[FN]/activation/response [SN, S2, sig] B->>B: verify sig, derive same pw, store SN + pw B->>M: reconnect as SN / pw G->>M: disable FN client (or keep for rescue / re-enrollment) diff --git a/docs/sn-as-username-process.md b/docs/sn-as-username-process.md index af3a08b..e6c70ad 100644 --- a/docs/sn-as-username-process.md +++ b/docs/sn-as-username-process.md @@ -118,14 +118,14 @@ sequenceDiagram participant G as Go backend B->>B: random Client ID, X25519 pair (b, B), nonce n1 B->>M: CONNECT anonymous, clientId=random (TLS) - B->>M: SUBSCRIBE enroll/response/{cid} (own topic only) - B->>G: enroll/request/{cid} {B, n1, mac} - G->>G: reserve {cid}, assign FN, ephemeral (s, S) - G->>G: shared = X25519(s, B), pw = HKDF(shared, salt=n1, info=label|FN) + B->>M: SUBSCRIBE enroll/response/[cid] (own topic only) + B->>G: enroll/request/[cid] [B, n1, mac] + G->>G: reserve [cid], assign FN, ephemeral (s, S) + G->>G: shared = X25519(s, B), pw = HKDF(shared, salt=n1, info = label, FN) G->>M: dynsec createClient FN, pw, clientid=FN, role board-bootstrap - G->>B: enroll/response/{cid} {FN, S, sig} (not retained) + G->>B: enroll/response/[cid] [FN, S, sig] (not retained) B->>B: verify sig, shared = X25519(b, S), same pw - B->>B: persist FN + pw to flash, then reconnect as FN + B->>B: persist FN and pw to flash, then reconnect as FN ``` - `sig` = Ed25519 over `S || B || n1 || clientid || FN`. Binding the FN and the Client ID means a reply for another request, board or identity does not verify. @@ -161,17 +161,17 @@ sequenceDiagram participant G as Go backend participant M as Mosquitto participant B as Board (FN session) - B->>B: fresh X25519 pair (b2, B2), nonce n2, SAS = digits(hash(B2 || n2 || FN)) - B->>G: board/{FN}/activation/request {B2, n2} + B->>B: fresh X25519 pair (b2, B2), nonce n2, SAS = digits(hash(B2, n2, FN)) + B->>G: board/[FN]/activation/request [B2, n2] G->>O: pending request FN, MAC label, SAS, time O->>G: choose SN, enter activation code, confirm SAS matches the board - G->>G: DB: ACTIVATING (FN, SN, generation g+1), unique constraint - G->>G: ephemeral (s2, S2), shared2, pw_sn = HKDF(shared2, salt=n2, info=label|SN|g+1) + G->>G: DB: ACTIVATING (FN, SN, next generation), unique constraint + G->>G: ephemeral (s2, S2), shared2, pw_sn = HKDF(shared2, salt=n2, info = label, SN, generation) G->>M: dynsec create or update client SN: pw_sn, role vending-device, clientid = FN - G->>B: board/{FN}/activation/response {SN, g+1, S2, sig} - B->>B: verify sig, derive pw_sn, persist SN + pw_sn + generation, reconnect + G->>B: board/[FN]/activation/response [SN, next generation, S2, sig] + B->>B: verify sig, derive pw_sn, persist SN, pw_sn and generation, reconnect B->>M: CONNECT username=SN, clientId=FN, password=pw_sn - M-->>G: first message on device/{SN}/... (or presence) + M-->>G: first message on device/[SN]/... (or presence) G->>G: DB: ACTIVE, disable the FN client, audit ```