feat: add introduction encoding

.wordlist.txt

@@ -23,9 +23,12 @@ centric
 Changelog
 channelConfig
 channelId
+chatintro
 ciphertext
+CLI
 closeChannel
 config
+confusable
 ConnectionStatus
 ConnectionStatusEvent
 ContentFrame
@@ -104,6 +107,7 @@ implementors
 Implementors
 Inclusivity
 Init
+IntroBundle
 IPersistence
 ipv
 iterable
@@ -158,8 +162,10 @@ onMessageSent
 OpenAPI
 openChannel
 parityRate
+Parsers
 PartiallyConnected
 PascalCase
+Patryk
 Pax
 permissionless
 plaintext
@@ -171,6 +177,7 @@ Prem
 proto
 protobuf
 ProtocolsConfig
+pubkey
 pubsub
 rateLimitConfig
 RateLimitConfig
@@ -245,6 +252,8 @@ uint
 uint
 unencrypted
 unvalidated
+url
+UTF
 UUID
 UX
 waku
@@ -256,6 +265,7 @@ Waku's
 WakuNode
 www
 xB
+XEdDSA
 yaml
 YAML
 yml

standards/application/introduction_encoding.md

@@ -0,0 +1,153 @@
+---
+title: Introduction Bundle Encoding
+name: introduction-bundle-encoding
+category: Standards Track
+tags: core, encoding
+editor:
+contributors:
+  - Patryk <patryk@status.im>
+  - Jazzz <jazz@status.im>
+---
+
+## Abstract
+
+This specification defines the encoding format for Introduction Bundles — the
+out-of-band information shared so that a remote party can initiate contact with
+the bundle publisher.
+
+## Background / Rationale / Motivation
+
+Users need a way to share contact information across arbitrary channels
+(messaging apps, emails, QR codes, URLs, CLI terminals) without relying on a
+centralized directory. The Introduction Bundle provides the cryptographic
+material required to establish an encrypted conversation.
+
+The encoding must be:
+- Copy-paste safe across arbitrary text transports.
+- Space-efficient for manual sharing.
+- Version-aware to support protocol evolution.
+
+## Theory / Semantics
+
+An Introduction Bundle is bound to a specific protocol version; its encoded
+form identifies the version unambiguously.
+
+### Why ASCII, Not Unicode
+
+The encoded string consists entirely of printable ASCII. This is a natural
+consequence of the design rather than a defensive choice against Unicode:
+
+1. **No human-readable content.** The format contains a fixed prefix, a numeric
+   version, and a binary-to-text encoded payload. These components do not
+   require characters outside ASCII. Common binary-to-text encodings such as
+   hex, base32, and base64 produce ASCII output.
+2. **Encoding stability.** Printable ASCII characters are represented
+   identically in widely deployed text encodings such as UTF-8 and Latin-1,
+   avoiding ambiguity in character interpretation across transports.
+3. **Restricted visible alphabet.** Limiting the character set reduces the risk
+   of visually confusable or non-rendering characters during manual comparison,
+   transcription, or copy-paste across different platforms, terminals, and
+   fonts.
+
+### Delimiter Choice
+
+The `_` character is present in the alphabets of common binary-to-text
+encodings (hex, base32, base64url) and may therefore appear inside the payload.
+Parsers MUST split the encoded string on the **first three** `_` characters;
+everything after the third `_` is the payload verbatim.
+
+The underscore was chosen because it is a printable ASCII character that is
+safe in URLs, filenames, and plain text without requiring escaping. Delimiters
+outside this category (e.g., `.` or `:`) may require percent-encoding in
+certain URL contexts, undermining the transport-safety goal.
+
+## Wire Format Specification / Syntax
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
+"SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this
+document are to be interpreted as described in [RFC 2119].
+
+### Text Format
+
+The Introduction Bundle is encoded as a single ASCII string:
+
+```
+logos_<namespace>_<version>_<payload>
+```
+
+| Field       | Description                                                       |
+|-------------|-------------------------------------------------------------------|
+| `logos`     | Fixed prefix. Identifies the string as a Logos protocol artifact. |
+| `namespace` | Domain identifier. Distinguishes bundle types.                    |
+| `version`   | Protocol version number. Decimal integer, no leading zeros.       |
+| `payload`   | Binary-to-text encoded payload (version-specific).                |
+
+Fields are separated by `_` (underscore).
+
+### V1
+
+#### Parameters
+
+| Parameter   | Value                          |
+|-------------|--------------------------------|
+| `namespace` | `chatintro`                    |
+| `version`   | `1`                            |
+| `encoding`  | base64url, no padding          |
+| `payload`   | Protobuf-encoded `IntroBundle` |
+
+#### Payload Encoding
+
+V1 uses **base64url without padding** ([RFC 4648 §5], padding
+characters `=` omitted). This encoding was chosen for:
+
+- URL safety without percent-encoding.
+- ~33% size overhead (compared to ~100% for hex).
+- Wide library support across languages.
+
+Future versions MAY choose a different binary-to-text encoding.
+
+#### Binary Payload
+
+The payload is a Protocol Buffers (proto3) encoding of:
+
+```proto
+syntax = "proto3";
+
+message IntroBundle {
+  bytes installation_pubkey = 1;  // 32 bytes, X25519
+  bytes ephemeral_pubkey    = 2;  // 32 bytes, X25519
+  bytes signature           = 3;  // 64 bytes, XEdDSA
+}
+```
+
+The encoding MUST use standard proto3 serialization. Canonical (deterministic)
+serialization is NOT REQUIRED; decoders MUST accept any valid proto3 encoding
+of the message.
+
+#### Encoding Procedure
+
+1. Construct the `IntroBundle` protobuf message.
+2. Serialize using proto3 encoding (~134 bytes).
+3. Encode as base64url without padding (~179 characters).
+4. Prepend the preamble with version prefix.
+
+The resulting string is ~197 printable ASCII characters.
+
+## Security/Privacy Considerations
+
+The signature prevents tampering but does not provide confidentiality. Bundles
+should be transmitted over channels appropriate for the user's threat model.
+
+## Copyright
+
+Copyright and related rights waived via [CC0].
+
+## References
+
+- [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) — Key words for use in RFCs
+- [RFC 4648 §5](https://www.rfc-editor.org/rfc/rfc4648#section-5) — Base 64 Encoding with URL and Filename Safe Alphabet
+- [CC0](https://creativecommons.org/publicdomain/zero/1.0/) — Creative Commons Zero Public Domain Dedication
+
+[RFC 2119]: https://www.ietf.org/rfc/rfc2119.txt
+[RFC 4648 §5]: https://www.rfc-editor.org/rfc/rfc4648#section-5
+[CC0]: https://creativecommons.org/publicdomain/zero/1.0/