77f72ed ("fix: enable query logging privacy mode by default", v3.2.0) changed exactly one thing: log.privacy from false to true in blocky/config.yaml's options: block. Per ADR-0011 that reached new installations only. Every operator who had pressed Save before v3.2.0 has false pinned in their persisted configuration and still does.
blocky/translations/en.yaml tells them otherwise, in writing: "The addon defaults this to true for privacy protection." For that population the statement is false.
Blast radius
Larger than the option's name suggests. Blocky's log.privacy governs the general application log, not the query log — upstream describes it as obfuscating "log output … for user sensitive data like request domains or responses" under the log section. So query_log.type defaulting to "" is irrelevant: the add-on log visible in the Home Assistant UI, and included in support downloads, carries unobfuscated domain names.
Open question for whoever picks this up: at which log level Blocky actually writes per-query lines to the application log. Upstream docs do not say, and the wording of the docs entry below depends on it. Worth settling against Blocky's source or a running instance before writing the text.
Proposed fix
Two parts, neither of which touches the schema.
1. A Troubleshooting entry in blocky/DOCS.md. House style, alongside the existing entries; v3.2.0 is the boundary. Something in the shape of:
Logs show plaintext domain names
The add-on sets log.privacy to true, but a default only applies until your first Save — after that your stored value wins. If you configured this add-on before v3.2.0, yours is still false. Set it under Configuration → Log.
Note the ordering interaction with #303, which places a missing-option entry first as the only config-editing problem among runtime ones. This is a second config-editing entry.
2. A one-time warning at start when the rendered config carries privacy: false, pointing at that entry. The log is the crime scene here — whoever is exposed to the plaintext domains sees the warning right next to them.
Mechanically this reads privacy: false out of the rendered config, which makes it format-coupled: the detection belongs in usr/lib/blocky/guards.sh as a pure function, pinned by a render-test golden and exercised by scripts/test-guards.sh, Standard Mode only (ADR-0004). It is not a degrade-warn in the sense of ADR-0007 — nothing was dropped, the template emitted exactly what was configured — so it needs no intent read from options.json. It is also not a Guard as CONTEXT.md defines one, since it neither aborts nor degrades; it is an advisory, and should not be dignified into a new category for a single option.
Considered and rejected: a new key
ADR-0011's one lever that reaches existing operators is to introduce a new key and retain log.privacy under ADR-0005 — the start_verify pattern from 20b4958, so the machinery exists and the cost is known.
Rejected, because the ADR makes that lever justification-bearing and this case does not clear the bar. Blocky's own default is false; the add-on deviates deliberately. Taking the new-key route would silently impose that deviation, on update and without warning, on operators who never chose it — including anyone holding false on purpose while troubleshooting, which en.yaml explicitly recommends. A privacy posture we prefer is not the same thing as a defect that makes the add-on wrong for everyone. Revisit only if evidence appears that operators are actually harmed and the advisory is not reaching them.
Provenance
Surfaced while grilling the default-pinning finding from docs/research/home-assistant-addon-options.md §4 (#293), recorded as out of scope by map #291. Original intent: #73 via #118.
77f72ed("fix: enable query logging privacy mode by default", v3.2.0) changed exactly one thing:log.privacyfromfalsetotrueinblocky/config.yaml'soptions:block. Per ADR-0011 that reached new installations only. Every operator who had pressed Save before v3.2.0 hasfalsepinned in their persisted configuration and still does.blocky/translations/en.yamltells them otherwise, in writing: "The addon defaults this to true for privacy protection." For that population the statement is false.Blast radius
Larger than the option's name suggests. Blocky's
log.privacygoverns the general application log, not the query log — upstream describes it as obfuscating "log output … for user sensitive data like request domains or responses" under thelogsection. Soquery_log.typedefaulting to""is irrelevant: the add-on log visible in the Home Assistant UI, and included in support downloads, carries unobfuscated domain names.Open question for whoever picks this up: at which log level Blocky actually writes per-query lines to the application log. Upstream docs do not say, and the wording of the docs entry below depends on it. Worth settling against Blocky's source or a running instance before writing the text.
Proposed fix
Two parts, neither of which touches the schema.
1. A Troubleshooting entry in
blocky/DOCS.md. House style, alongside the existing entries; v3.2.0 is the boundary. Something in the shape of:Note the ordering interaction with #303, which places a missing-option entry first as the only config-editing problem among runtime ones. This is a second config-editing entry.
2. A one-time warning at start when the rendered config carries
privacy: false, pointing at that entry. The log is the crime scene here — whoever is exposed to the plaintext domains sees the warning right next to them.Mechanically this reads
privacy: falseout of the rendered config, which makes it format-coupled: the detection belongs inusr/lib/blocky/guards.shas a pure function, pinned by a render-test golden and exercised byscripts/test-guards.sh, Standard Mode only (ADR-0004). It is not a degrade-warn in the sense of ADR-0007 — nothing was dropped, the template emitted exactly what was configured — so it needs no intent read fromoptions.json. It is also not a Guard asCONTEXT.mddefines one, since it neither aborts nor degrades; it is an advisory, and should not be dignified into a new category for a single option.Considered and rejected: a new key
ADR-0011's one lever that reaches existing operators is to introduce a new key and retain
log.privacyunder ADR-0005 — thestart_verifypattern from20b4958, so the machinery exists and the cost is known.Rejected, because the ADR makes that lever justification-bearing and this case does not clear the bar. Blocky's own default is
false; the add-on deviates deliberately. Taking the new-key route would silently impose that deviation, on update and without warning, on operators who never chose it — including anyone holdingfalseon purpose while troubleshooting, whichen.yamlexplicitly recommends. A privacy posture we prefer is not the same thing as a defect that makes the add-on wrong for everyone. Revisit only if evidence appears that operators are actually harmed and the advisory is not reaching them.Provenance
Surfaced while grilling the default-pinning finding from
docs/research/home-assistant-addon-options.md§4 (#293), recorded as out of scope by map #291. Original intent: #73 via #118.