Skip to content
This repository was archived by the owner on Jun 5, 2026. It is now read-only.

Chat Inbox#83

Closed
jazzz wants to merge 9 commits into
masterfrom
jazzz/inbox_xk0
Closed

Chat Inbox#83
jazzz wants to merge 9 commits into
masterfrom
jazzz/inbox_xk0

Conversation

@jazzz

@jazzz jazzz commented Sep 23, 2025

Copy link
Copy Markdown
Contributor

This PR adds a specification which describes a chat initialization protocol.

This replaces the previous effort #72 as the changes are substantial. This specification incorporates the feedback from the previous version - Specifically:

  • Removes Waku specific details (such as ContentTopic) and introduces a delivery_address abstraction
  • Removed inbox_address for simplicity
  • Defers Conversation_id semantics to a implementation specific specification. #TODO: Link
  • Defer envelope definition and framing strategy to implementation specific specification. #TODO: Link
  • Adds clarity on MessageFlow

In addition it also:

  • updates the encryption primitives to provide, mutual authentication.

@jazzz jazzz changed the title Chat Inbox (XK0) Chat Inbox Jan 20, 2026

@osmaczko osmaczko left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The specification might benefit from explicitly referencing the Chat Framework, for example by:

  • Stating that Inbox is an Initialization Protocol as defined by the Chat Framework
  • Referring to the PreMessage as the IntroductionBundle for this protocol (or documenting the mapping)
  • Clarifying that the out-of-band exchange of the PreMessage falls under the responsibility of the Discovery Protocol

I -->> R: Subscribe

note over R,S: Send Out-of-Band
R ->> S : PreMessage(IK,EK,<delivery_address>)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is PreMessage a concrete realization of an IntroductionBundle mentioned in the Chat Framework specification?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correct. That has been renamed. Will update

R ->> S : PreMessage(IK,EK,<delivery_address>)

note over R,S: Sent In-Band
S ->> I : M1

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is M1 a InboxHandshakeV1?

@jazzz jazzz Feb 9, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

InboxHandshakeV1 is sufficient here. There is only one message type defined currently so yes M1 = InboxHandshakeV1 but that is not categorically true into the future.

This diagram is aimed at representing Message flow generically.

Comment on lines +146 to +148
- **ephemeral:** This field contains the remotes ephemeral public key.
- **key_ref:** This field contains the recipient key identifier used in the handshake. This value is 4 bytes long.
- **static:** this field contains the remotes static public key. This value is encrypted according to the noise protocol to hide the senders identity.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Doesn't match the protobuf naming


## Implementation Suggestions (optional)

Recipients ephemeral key is not signed, and is susceptible to tampering by an active attacker during transit out of band. Implementors SHOULD keep the number of valid keys as little as possible. Revoking keys after a defined period of time, and only generating keys when needed minimizes the ability for an attacker to substitute weak keys

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the unsigned EK risk here actually a confidentiality concern?Since the Recipient generates and tracks all their own EKs, a substituted EK would fail the key lookup on the Recipient side. So isn't this effectively a DoS (silently lost invite) rather than a "weak key" / forward secrecy issue?

Also, is the decision not to sign the ephemeral key still the case? According to logos-messaging/libchat#27, the IntroductionBundle is expected to contain a signature.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You are correct to point out this inconsistency.

Originally This Spec used a XK0 Handshake which was removed in this commit in favor of X3DH.

This spec has not been fully updated.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since the Recipient generates and tracks all their own EKs, a substituted EK would fail the key lookup on the Recipient side. So isn't this effectively a DoS (silently lost invite) rather than a "weak key" / forward secrecy issue?

The issue here is when the moment of compromise occurs.

Signing of keys allows the compromise to be detected by the sender before any potentially secret material has been transmitted. Unsigned keys can only be detected by the recipient - which leaves a larger attack surface.

While conversation initialization would fail in both cases, unsigned keys provides the building blocks for more complex attacks.

@igor-sirotin igor-sirotin left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see there's many TODOs, and the implementation went further and is now inconsistent with this spec, but I think we can get it merged and continue iterating on it later. It's still a raw spec anyway.

Comment thread standards/application/inbox.md Outdated

To make this efficient, the Sender includes a short identifier for the key.

Calculated as: `blake2b(utf8ToBytes('WAP') || K)`[0..4]

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is WAP? Waku Application Protocol? 🤔
Not important at all, but would be nice to specify for clarity.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

WAP => Waku Application Protocols ; It was the suggested product name before the Logos Rebranding. Its out of date and will need an update

bytes responder_static = 3;
bytes responder_ephemeral = 4; // Replace with RKI to save bytes
}
InboxHeader header = 1;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
InboxHeader header = 1;
InboxHeaderV1 header = 1;

Co-authored-by: Igor Sirotin <igor.sirotin.1012@gmail.com>
@jazzz jazzz closed this May 22, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants