Define flat plus-tag encoding and collision rules

phg commented

2026-07-22 22:12:34 +00:00

Owner

Blocked by: #2, #4
Part of #1

Question

What canonical, reversible mapping turns each extracted Plus tag into exactly one flat Dovecot-visible Tag folder for a required per-instance mailbox hierarchy separator, while preserving intended spelling, preventing filesystem traversal and reserved-name problems, avoiding collisions, and defining behavior for empty, malformed, oversized, case-variant, Unicode, separator-containing, and otherwise unsafe tags?

Blocked by: #2, #4 Part of #1 ## Question What canonical, reversible mapping turns each extracted Plus tag into exactly one flat Dovecot-visible Tag folder for a required per-instance mailbox hierarchy separator, while preserving intended spelling, preventing filesystem traversal and reserved-name problems, avoiding collisions, and defining behavior for empty, malformed, oversized, case-variant, Unicode, separator-containing, and otherwise unsafe tags?

phg added the

wayfinder:grilling

label 2026-07-22 22:12:34 +00:00

phg referenced this issue

2026-07-22 22:13:01 +00:00

Validate the writable tag namespace with a concrete prototype #6

phg referenced this issue

2026-07-22 22:13:03 +00:00

Define the user documentation contract #11

phg referenced this issue

2026-07-22 22:13:03 +00:00

Define verification and release acceptance criteria #12

phg commented

2026-07-22 22:58:34 +00:00

Author

Owner

Claimed by Codex agent /root for a HITL decision session on 2026-07-23.

Claimed by Codex agent `/root` for a HITL decision session on 2026-07-23.

phg commented

2026-07-23 10:41:45 +00:00

Author

Owner

Previous claim released after its session aborted. Claimed by Claude Code agent for a fresh HITL decision session on 2026-07-23.

phg commented

2026-07-23 11:22:49 +00:00

Author

Owner

Resolution

Use a two-stage, canonical, reversible mapping from each valid Plus tag to one flat Tag folder:

Build the logical Tag-folder component with readable percent escaping.
Encode that logical component using Dovecot’s default modified UTF-7 storage representation to obtain the physical mailbox_list_layout = fs directory name.

Logical encoding

Preserve ordinary printable Unicode, spaces, and punctuation. Percent-encode the original UTF-8 bytes as uppercase %HH for:

literal %;
/;
the configured mailbox hierarchy separator;
ASCII control bytes and DEL;
Unicode control and format code points;
anything else unsafe for the filesystem or Dovecot mailbox component.

Literal % is always %25, making escape-looking source text unambiguous. Dovecot modified UTF-7 handles remaining Unicode in the physical name; for example, logical ä becomes physical &AOQ-. Decode in reverse order: canonical modified UTF-7, then %HH, yielding the exact original UTF-8 Plus tag.

Use no universal prefix. Prevent reserved-name conflicts by escaping the first UTF-8 byte when the otherwise encoded logical name begins with . or ~, equals . or .., case-insensitively equals INBOX, or exactly equals lowercase cur, new, or tmp. Examples include cur → %63ur and ~team → %7Eteam.

Identity and collisions

Plus-tag identity is exact validated UTF-8 bytes. Preserve case and Unicode sequence without case-folding or normalization: Sales and sales, and NFC and decomposed spellings, remain distinct Tag folders. Deduplicate exact semantic suffixes only.

The encoder emits uppercase escapes only. A decoder must decode and re-encode, accepting the name only when the result matches byte-for-byte. Reject lowercase escapes, unnecessary escapes, invalid hex, malformed/noncanonical modified UTF-7, invalid UTF-8, and unescaped reserved forms. This canonicality plus % escaping and reversible modified UTF-7 prevents aliases and collisions.

Invalid and oversized inputs

The recipient-parsing contract already rejects empty suffixes, malformed recipient occurrences, and invalid SMTPUTF8 before encoding. Continue processing valid sibling occurrences and other Plus tags.

After both encoding stages, reject only a Plus tag whose physical component exceeds the effective filesystem NAME_MAX or Dovecot mailbox-name limit. Do not truncate it or replace it with a digest/catalog alias. Continue creating the message’s other valid Message projections. Emit a rate-limited diagnostic containing the failure class, encoded length, and a digest—not the recipient address or full Plus tag.

Noncanonical names requested through the mounted namespace never create aliases: return the appropriate not-found or unsupported/read-only error and emit a rate-limited diagnostic.

## Resolution Use a two-stage, canonical, reversible mapping from each valid Plus tag to one flat Tag folder: 1. Build the logical Tag-folder component with readable percent escaping. 2. Encode that logical component using Dovecot’s default modified UTF-7 storage representation to obtain the physical `mailbox_list_layout = fs` directory name. ### Logical encoding Preserve ordinary printable Unicode, spaces, and punctuation. Percent-encode the original UTF-8 bytes as uppercase `%HH` for: - literal `%`; - `/`; - the configured mailbox hierarchy separator; - ASCII control bytes and DEL; - Unicode control and format code points; - anything else unsafe for the filesystem or Dovecot mailbox component. Literal `%` is always `%25`, making escape-looking source text unambiguous. Dovecot modified UTF-7 handles remaining Unicode in the physical name; for example, logical `ä` becomes physical `&AOQ-`. Decode in reverse order: canonical modified UTF-7, then `%HH`, yielding the exact original UTF-8 Plus tag. Use no universal prefix. Prevent reserved-name conflicts by escaping the first UTF-8 byte when the otherwise encoded logical name begins with `.` or `~`, equals `.` or `..`, case-insensitively equals `INBOX`, or exactly equals lowercase `cur`, `new`, or `tmp`. Examples include `cur` → `%63ur` and `~team` → `%7Eteam`. ### Identity and collisions Plus-tag identity is exact validated UTF-8 bytes. Preserve case and Unicode sequence without case-folding or normalization: `Sales` and `sales`, and NFC and decomposed spellings, remain distinct Tag folders. Deduplicate exact semantic suffixes only. The encoder emits uppercase escapes only. A decoder must decode and re-encode, accepting the name only when the result matches byte-for-byte. Reject lowercase escapes, unnecessary escapes, invalid hex, malformed/noncanonical modified UTF-7, invalid UTF-8, and unescaped reserved forms. This canonicality plus `%` escaping and reversible modified UTF-7 prevents aliases and collisions. ### Invalid and oversized inputs The recipient-parsing contract already rejects empty suffixes, malformed recipient occurrences, and invalid SMTPUTF8 before encoding. Continue processing valid sibling occurrences and other Plus tags. After both encoding stages, reject only a Plus tag whose physical component exceeds the effective filesystem `NAME_MAX` or Dovecot mailbox-name limit. Do not truncate it or replace it with a digest/catalog alias. Continue creating the message’s other valid Message projections. Emit a rate-limited diagnostic containing the failure class, encoded length, and a digest—not the recipient address or full Plus tag. Noncanonical names requested through the mounted namespace never create aliases: return the appropriate not-found or unsupported/read-only error and emit a rate-limited diagnostic.

phg closed this issue

2026-07-23 11:22:49 +00:00

phg referenced this issue

2026-07-23 11:23:05 +00:00

Specify the writable Dovecot plus-tag filesystem #1

Rows
Columns

Define flat plus-tag encoding and collision rules #5

Question

Resolution

Logical encoding

Identity and collisions

Invalid and oversized inputs