Chat Private by jazzz · Pull Request #93 · logos-messaging/specs

jazzz · 2025-10-26T21:47:08Z

This PR adds a specification which describes a conversation protocol for pairwise communication called PRIVATE1.

It covers payload generation and operation after a key has been agreed upon by both parties.

Notes

This may eventually be simplified and use Reliable Channels but its explicit in how it utilizes SDS + segmentation and the reasons for doing so.

jazzz · 2025-10-28T23:43:05Z

+
+The following mappings connect PRIVATE1 concepts to SDS fields:
+
+- `sender_id`: !TODO: This requires PRIVATE1 to be identity aware


Unsure exactly what the best course of action is here. Recent changes to SDS requires an sender_id be attached the the SdsMessage.

This then brings in a concept of identity to this specification. Its definitely possible to introduce Identity concepts in order to pass them through to SDS, however it seems like a lot of added complexity

jonesmarvin8 · 2026-02-07T00:41:59Z

+- **[DOUBLERATCHET]** "The Double Ratchet Algorithm", Signal, 2016.
+  https://signal.org/docs/specifications/doubleratchet/
+
+- **[SDS]** "Scalable Data Sync Specification", vac, 2024.


All of these github references from vacp2p and waku-org are broken.

osmaczko

Looks good overall. The reasoning behind the Content -> Segmentation -> Reliability -> Encryption layering makes sense.

Please remember to address the TODOs before merging.

osmaczko · 2026-02-08T14:06:54Z

+```mermaid
+flowchart LR
+    Content:::plain--> PrivateV1 --> Payload:::plain
+    classDef plain fill:none,stroke:transparent;
+```


Suggested change

```mermaid

flowchart LR

Content:::plain--> PrivateV1 --> Payload:::plain

classDef plain fill:none,stroke:transparent;

```

```mermaid

flowchart LR

Content:::plain --> PrivateV1

PrivateV1 --> F1[Frame 1] --> P1[Payload 1]:::plain

PrivateV1 -.-> F2[Frame 2] -.-> P2[Payload 2]:::plain

PrivateV1 -.-> FN[Frame N] -.-> PN[Payload N]:::plain

classDef plain fill:none,stroke:transparent;

I generally like these changes, but looking to understand more to see if there is more optimizations to be made.

I see two changes here.

An explicit reference to Frames

An specific update the the cardinality of messages.

I can see # 2 being an improvement as it explicitly refers to segmentation being a responsibility of the protocol.

At a high level does adding Frames increase understanding at a 40,000ft view?

At a high level does adding Frames increase understanding at a 40,000ft view?

Don’t have a strong opinion here. Including frames makes it clear at first glance that segmentation happens in the chat protocol rather than in the delivery service.

I agree that Frames seem to be unnecessary here.

Maybe something like this?

flowchart LR Content:::plain--> PrivateV1 --> Payloads@{ shape: stacked-rectangle } classDef plain fill:none; class Payloads plain;

Loading

osmaczko · 2026-02-08T14:11:06Z

+Implementation specifics:
+- Error correction is not used, as reliable delivery is already provided by lower layers. 
+- `segmentSize` = `max_seg_size`
+- All payloads regardless of size are wrapped in a segmentation message.


This contradicts segmentation specs:

Messages whose payload size is ≤ segmentSize are sent unmodified.

Great point.

I specifically have suggested a change in that PR.

Sending the message unmodified violates the functional requirement of "deterministic decoding".

To decode those messages one would first attempt to decode as a Segmentation message, and then on failure, assume its a different type.

I'd prefer to spend the extra 4 bytes and make it explicit.

I'd prefer to spend the extra 4 bytes and make it explicit.

Totally agree 👍

igor-sirotin

I wish I read it earlier!

igor-sirotin · 2026-04-16T16:44:05Z

+
+This specification defines PRIVATE1, a conversation protocol for establishing secure, full-duplex encrypted communication channels between two participants. PRIVATE1 provides end-to-end encryption with forward secrecy and post-compromise security using the Double Ratchet algorithm, combined with reliable message delivery via Scalable Data Sync (SDS) and efficient segmentation for transport-constrained environments.
+
+The protocol is transport-agnostic and designed to support both direct messaging and as a foundation for group communication systems. PRIVATE1 ensures payload confidentiality, content integrity, sender privacy, and message reliability while remaining resilient to network disruptions and message reordering.


I'm not sure but something sounds wrong in ... support both direct messaging and as a foundation .... I get the meaning, just not sure of the language.

I think you know better, I'm just highlighting

Suggested change

The protocol is transport-agnostic and designed to support both direct messaging and as a foundation for group communication systems. PRIVATE1 ensures payload confidentiality, content integrity, sender privacy, and message reliability while remaining resilient to network disruptions and message reordering.

The protocol is transport-agnostic and designed to support direct messaging and serve as a foundation for group communication systems. PRIVATE1 ensures payload confidentiality, content integrity, sender privacy, and message reliability while remaining resilient to network disruptions and message reordering.

igor-sirotin · 2026-05-03T21:09:25Z

+```mermaid
+flowchart LR
+    Content:::plain--> PrivateV1 --> Payload:::plain
+    classDef plain fill:none,stroke:transparent;
+```


I agree that Frames seem to be unnecessary here.

Maybe something like this?

flowchart LR Content:::plain--> PrivateV1 --> Payloads@{ shape: stacked-rectangle } classDef plain fill:none; class Payloads plain;

Loading

igor-sirotin · 2026-05-03T21:22:13Z

+- `conversation_id` SHOULD be consistent across applications to maintain interoperability
+
+Additionally implementations MUST determine the following constants:
+- `max_seg_size` - maximum segmentation size to be used.


Isn't this dictated by the transport used by an application?
If yes, then this max_seg_size should be defined by application, not protocol implementation? Or am I not getting "implementation" term here?

Isn't this dictated by the transport used by an application?

When this was modeled it implemented relaibility inside of the converastion.

then this max_seg_size should be defined by application, n

sure. However we're trying to avoid a circular dependency. max_seg_size is a paramter that must be passed in.

igor-sirotin · 2026-05-03T22:11:12Z

+- Clients SHALL only pass `content` frames to applications
+- Clients MAY drop unrecognized frame types


Is "clients" same thing as "implementations"?

Suggested change

- Clients SHALL only pass `content` frames to applications

- Clients MAY drop unrecognized frame types

- Implementations SHALL only pass `content` frames to applications

- Implementations MAY drop unrecognized frame types

Cleanup of Arch, Initialization and Segmentation frame handling + initialization towards semBr Abstract away contentFrame update frame handing Remove delivery address remove partial order property Update background readability updates Update encryption and segmentation Remove stale section update payload delivery warnings Update SDS initialization Update security considerations Cleanup review comments spelling fixes fix: pyspelling config Update DR params Update standards/application/privatev1.md Co-authored-by: Igor Sirotin <igor.sirotin.1012@gmail.com> Clarify implementation

…pecs Pristine copies of the last messaging specs not covered by #315/#331, imported as-is from logos-messaging/specs so the adaptation diff is isolated in the following commit: - chat-framework (logos-messaging/specs#81) - privatev1 (logos-messaging/specs#93) - introduction-encoding (logos-messaging/specs#101) - contentframe (logos-messaging/specs#82) - tor-push (Waku v2 Tor Push) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

jazzz force-pushed the jazzz/private branch from 1cff184 to bfe3f14 Compare October 28, 2025 22:18

jazzz commented Oct 28, 2025

View reviewed changes

jazzz marked this pull request as ready for review October 28, 2025 23:44

jazzz requested review from jm-clius and plopezlpz October 28, 2025 23:44

jazzz mentioned this pull request Oct 29, 2025

feat: add segmentation spec #91

Merged

jazzz requested review from Ivansete-status and osmaczko November 4, 2025 09:17

jazzz force-pushed the jazzz/private branch from f00cff3 to ac0d17a Compare January 20, 2026 21:56

jazzz mentioned this pull request Jan 25, 2026

Implement PrivateV1 Conversation ID logos-messaging/libchat#26

Closed

jazzz marked this pull request as draft February 2, 2026 17:33

jonesmarvin8 reviewed Feb 7, 2026

View reviewed changes

osmaczko approved these changes Feb 8, 2026

View reviewed changes

igor-sirotin approved these changes May 3, 2026

View reviewed changes

jazzz force-pushed the jazzz/private branch from f449fbd to 732690e Compare May 22, 2026 23:32

Merge branch 'master' of github.com:waku-org/specs into jazzz/private

d32d10b

jazzz marked this pull request as ready for review May 22, 2026 23:40

jazzz merged commit a39b57f into master May 22, 2026
1 check failed

jazzz deleted the jazzz/private branch May 22, 2026 23:40

igor-sirotin mentioned this pull request May 26, 2026

docs(messaging): move remaining specs from logos-messaging/specs logos-co/logos-lips#346

Draft


		The following mappings connect PRIVATE1 concepts to SDS fields:

		- `sender_id`: !TODO: This requires PRIVATE1 to be identity aware


		This specification defines PRIVATE1, a conversation protocol for establishing secure, full-duplex encrypted communication channels between two participants. PRIVATE1 provides end-to-end encryption with forward secrecy and post-compromise security using the Double Ratchet algorithm, combined with reliable message delivery via Scalable Data Sync (SDS) and efficient segmentation for transport-constrained environments.

		The protocol is transport-agnostic and designed to support both direct messaging and as a foundation for group communication systems. PRIVATE1 ensures payload confidentiality, content integrity, sender privacy, and message reliability while remaining resilient to network disruptions and message reordering.

		- Clients SHALL only pass `content` frames to applications
		- Clients MAY drop unrecognized frame types

Conversation

jazzz commented Oct 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Notes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

osmaczko left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

igor-sirotin left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jazzz commented Oct 26, 2025 •

edited

Loading