Skip to content
Draft
25 changes: 24 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ This repository is private. The implementation is under review and has not been

- Runner protocol: [`proto/polymorfa/signal/v1/signal_service.proto`](proto/polymorfa/signal/v1/signal_service.proto), version `1`, subprotocol `polymorfa.signal.v1`, originating at `b6d5f5f`.
- Application API: [`docs/app-api.openapi.json`](docs/app-api.openapi.json). JSON field names use snake_case. Event and message timestamps use Unix seconds; lease expiry uses Unix milliseconds internally.
- Signal libraries: exact `polymorfa/whatsapp-rust` revision `4b3b13cacd40a27573d0246386db553ef887539b`, the unmerged [recordstore/Signal operations producer PR](https://github.com/polymorfa/whatsapp-rust/pull/5). All five normal/dev crate families use this same source. A successful local build does not make that producer a released dependency.
- Signal libraries: core from `oxidezap/whatsapp-rust` at `2671430db6161c01c507587d0e3c90dcf153aa85`, with `wacore-recordstore` and `wacore-signal-ops` owned by this workspace. Status-session storage and identity finalization live in the local operations adapter. Local checks do not establish a released service or native-client acceptance.
- Rust MSRV: `1.95`. The checked-in toolchain selects `1.95.0`.

The server connection uses a project credential in `Authorization`, never in a URL or browser. The local API uses a separate application bearer secret. It rejects every authenticated request with an `Origin` header, including `Origin: null`, and supplies no CORS permission. Browser/WASM remote transport is unavailable until Polymorfa provides a distinct, short-lived client grant backed by live authorization. Never put the project credential or application secret in a browser.
Expand Down Expand Up @@ -162,3 +162,26 @@ cargo build --release --locked
Without the PostgreSQL variable, local tests explicitly report that PG conformance was not exercised. CI requires it. Tests exercise real SQLite and PostgreSQL store conformance; per-slot authentication; a fake Polymorfa WebSocket with Hello/Welcome/claims; actual two-device Signal encryption/decryption; signed webhook failure/ACK and SSE delivery; encrypted SendStanza; consent-off history; expiry, stale writes and crash replay; and the five-per-second ceiling. The transport peer is a fixture, not a real runner or WhatsApp account.

Release still requires the pinned library producer to merge, backend/SDK/CLI/docs consumers to integrate on explicit revisions, real-account pairing/send/receive/media/history/group/retry acceptance, and the private AGPL/legal review plus owner publication approval. Repository visibility, package/image publication and production rollout controls remain unchanged by this implementation. The service adds no staff control authority; backend-owned eligibility and counts-only diagnostics stay in the Polymorfa control plane.

## Receiving status publications

`RunnerRequest.status_receive` is a distinct operation. Implement it before
accepting status publications: the nested `Receive` preserves origin, sender,
alternate identity and provider time; `status_kind` identifies personal, group
or channel scope. Apply `status_session` only to pairwise `pkmsg`/`msg` session
storage, keeping identity keys and prekeys shared. Sender keys retain their
existing group/sender scope. Keep phone-number to linked-identity migration,
identity replacement and session deletion consistent across both session stores.

An older service must return `CODE_UNSUPPORTED` without decrypting, delivering
or changing a chat session. Do not fall back to `receive`. The response remains
`ServiceResponse.receive`; plaintext stays in the customer-owned service.
The receiver delivers `status.received` with `status_scope` and the existing shared
content fields. Group publications retain their full protobuf while text and
media use the wrapped publication content. Replies and mention notifications
remain messages. Local synthetic tests do not establish live rollout eligibility.

Legacy group publication wrappers also return their classification for delivery
receipts, including after application acknowledgment. Delivered markers retain
only that classification, not plaintext. Empty markers written by older versions
have unknown classification; no sender or publication scope is guessed from them.
18 changes: 15 additions & 3 deletions crates/signal-ops/src/error.rs
Original file line number Diff line number Diff line change
Expand Up @@ -49,10 +49,22 @@ impl OpsError {
pub fn is_fence_lost(&self) -> bool {
match self {
OpsError::Store(e) => state_is_refused(e),
OpsError::Signal(SignalProtocolError::BackendError(_, source)) => source
.downcast_ref::<StoreError>()
.is_some_and(state_is_refused),
OpsError::Signal(error) => signal_state_is_refused(error),
_ => false,
}
}
}

fn signal_state_is_refused(error: &SignalProtocolError) -> bool {
let mut source: Option<&(dyn std::error::Error + 'static)> = Some(error);
while let Some(current) = source {
if current
.downcast_ref::<StoreError>()
.is_some_and(state_is_refused)
{
return true;
}
source = current.source();
}
false
}
63 changes: 55 additions & 8 deletions crates/signal-ops/src/inbound.rs
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,8 @@ pub enum Received {
/// Delivered before; the client only needs to send its receipt again.
AlreadyDelivered {
receipt_key: String,
/// Classification retained in the delivered marker, without plaintext.
group_status_wrapper: Option<bool>,
},
}

Expand All @@ -83,7 +85,7 @@ pub struct ReceivedMessage {
pub app_state_key_share: Option<wa::message::AppStateSyncKeyShare>,
}

fn receipt_key(request: &ReceiveRequest<'_>) -> String {
fn receipt_key(request: &ReceiveRequest<'_>, status_session: bool) -> String {
let mut hasher = Sha256::new();
for part in [
request.kind.as_str().as_bytes(),
Expand All @@ -93,6 +95,9 @@ fn receipt_key(request: &ReceiveRequest<'_>) -> String {
hasher.update(part);
hasher.update([0]);
}
if status_session {
hasher.update(b"status-session\0");
}
hasher.update(request.ciphertext);
hex::encode(hasher.finalize())
}
Expand Down Expand Up @@ -152,14 +157,18 @@ impl BufferEntry {
})
}

fn delivered(inserted_ms: u64) -> Self {
fn delivered(inserted_ms: u64, group_status_wrapper: Option<bool>) -> Self {
Self {
state: STATE_DELIVERED,
padding_version: 0,
identity_changed: false,
sender_key_rejected: false,
inserted_ms,
padded_plaintext: Vec::new(),
// A delivered marker never carries message content. Older readers
// ignore its trailing metadata; empty legacy markers stay unknown.
padded_plaintext: group_status_wrapper
.map(|flag| vec![u8::from(flag)])
.unwrap_or_default(),
}
}
}
Expand Down Expand Up @@ -214,7 +223,31 @@ impl<S: ServiceStore> SignalOps<S> {
/// Decrypt, buffer and classify one received payload. Sender-key
/// distributions inside it are stored in the same batch as the decrypt.
pub async fn receive(&self, request: ReceiveRequest<'_>) -> Result<Received, OpsError> {
let receipt_key = receipt_key(&request);
self.receive_scoped(request, false).await
}

/// Receive a status using a separate pairwise session when selected by
/// the caller's served configuration. Identity/prekeys and sender keys
/// remain shared. This does not enable status publishing.
pub async fn receive_status(
&self,
request: ReceiveRequest<'_>,
status_session: bool,
) -> Result<Received, OpsError> {
if status_session && request.kind == ReceiveKind::SenderKey {
return Err(OpsError::InvalidInput(
"sender keys cannot use a pairwise status session".into(),
));
}
self.receive_scoped(request, status_session).await
}

async fn receive_scoped(
&self,
request: ReceiveRequest<'_>,
status_session: bool,
) -> Result<Received, OpsError> {
let receipt_key = receipt_key(&request, status_session);
// Pairwise payloads can carry a sender-key distribution for this chat,
// so they also lock the sender's chain.
let chain = chain_key(request.chat, request.sender.as_str());
Expand Down Expand Up @@ -250,7 +283,14 @@ impl<S: ServiceStore> SignalOps<S> {
{
let entry = BufferEntry::decode(bytes)?;
if entry.state == STATE_DELIVERED {
return Ok(Received::AlreadyDelivered { receipt_key });
return Ok(Received::AlreadyDelivered {
receipt_key,
group_status_wrapper: match entry.padded_plaintext.as_slice() {
[0] => Some(false),
[1] => Some(true),
_ => None,
},
});
}
let content = classify(&entry.padded_plaintext, entry.padding_version, from_me)?;
return Ok(Received::Message(Box::new(ReceivedMessage {
Expand All @@ -272,12 +312,13 @@ impl<S: ServiceStore> SignalOps<S> {
EncKind::Message
};
let decrypted = self
.decrypt_into(
.decrypt_into_scoped(
&staged,
request.sender,
kind,
request.ciphertext,
request.device_identity,
status_session,
)
.await?;
(decrypted.plaintext, decrypted.identity_changed)
Expand All @@ -304,7 +345,7 @@ impl<S: ServiceStore> SignalOps<S> {
.put_aux(
Namespace::DecryptBuffer,
&receipt_key,
&BufferEntry::delivered(inserted_ms).encode(),
&BufferEntry::delivered(inserted_ms, None).encode(),
)
.await?;
staged.commit().await?;
Expand Down Expand Up @@ -384,7 +425,13 @@ impl<S: ServiceStore> SignalOps<S> {
.put_aux(
Namespace::DecryptBuffer,
receipt_key,
&BufferEntry::delivered(entry.inserted_ms).encode(),
&BufferEntry::delivered(
entry.inserted_ms,
classify(&entry.padded_plaintext, entry.padding_version, true)
.ok()
.map(|content| content.message.group_status_message_v2.is_set()),
)
.encode(),
)
.await?;
}
Expand Down
41 changes: 35 additions & 6 deletions crates/signal-ops/src/ops.rs
Original file line number Diff line number Diff line change
Expand Up @@ -423,6 +423,9 @@ impl<S: ServiceStore> SignalOps<S> {
pub(crate) async fn stores_over(&self, store: Arc<S>) -> Stores<S> {
Stores {
store,
status_session: false,
finalization_error: Arc::new(std::sync::Mutex::new(None)),
pending_identities: Arc::new(std::sync::Mutex::new(std::collections::HashMap::new())),
keys: self.authority.keys.read().await.clone(),
sender_key_locks: self.authority.sender_key_locks.clone(),
}
Expand Down Expand Up @@ -606,6 +609,10 @@ impl<S: ServiceStore> SignalOps<S> {
let mut found = Vec::new();
for ns in [Namespace::Session, Namespace::Identity] {
for address in self.store.scan_peer_addresses(ns, user).await? {
let address = address
.strip_suffix("_status")
.unwrap_or(&address)
.to_owned();
if let Some(device) = device_of(&address, user, server) {
found.push((address, device));
}
Expand Down Expand Up @@ -644,7 +651,11 @@ impl<S: ServiceStore> SignalOps<S> {
let batch: Vec<Arc<str>> =
addresses.iter().map(|a| Arc::from(a.as_str())).collect();
let staged = self.store.staged();
staged.delete_sessions_batch(&batch).await?;
let sessions: Vec<Arc<str>> = addresses
.iter()
.flat_map(|a| [Arc::from(a.as_str()), Arc::from(format!("{a}_status"))])
.collect();
staged.delete_sessions_batch(&sessions).await?;
staged.delete_identities_batch(&batch).await?;
staged.commit().await?;
Ok(())
Expand Down Expand Up @@ -718,12 +729,16 @@ impl<S: ServiceStore> SignalOps<S> {
let mut decided = std::collections::HashSet::new();
for (from, to) in &moves {
let first = !decided.contains(to);
if let Some(session) = staged.get_session(from).await? {
if first {
staged.put_session(to, &session).await?;
for suffix in ["", "_status"] {
let from_key = format!("{from}{suffix}");
let to_key = format!("{to}{suffix}");
if let Some(session) = staged.get_session(&from_key).await? {
if first {
staged.put_session(&to_key, &session).await?;
}
staged.delete_session(&from_key).await?;
moved.insert(to.clone());
}
staged.delete_session(from).await?;
moved.insert(to.clone());
}
if let Some(identity) = staged.load_identity(from).await? {
if first && staged.load_identity(to).await?.is_none() {
Expand Down Expand Up @@ -850,6 +865,19 @@ impl<S: ServiceStore> SignalOps<S> {
kind: EncKind,
ciphertext: &[u8],
device_identity: Option<&[u8]>,
) -> Result<Decrypted, OpsError> {
self.decrypt_into_scoped(staged, sender, kind, ciphertext, device_identity, false)
.await
}

pub(crate) async fn decrypt_into_scoped(
&self,
staged: &Arc<S>,
sender: &ProtocolAddress,
kind: EncKind,
ciphertext: &[u8],
device_identity: Option<&[u8]>,
status_session: bool,
) -> Result<Decrypted, OpsError> {
if kind == EncKind::PreKey {
let identity = *PreKeySignalMessage::try_from(ciphertext)?
Expand All @@ -862,6 +890,7 @@ impl<S: ServiceStore> SignalOps<S> {
.map_err(OpsError::BundleRefused)?;
}
let mut sessions = self.stores_over(staged.clone()).await;
sessions.status_session = status_session;
let mut identities = sessions.clone();
// libsignal reports a replaced identity for a prekey message but not
// for an ordinary `msg` that commits a session with another identity,
Expand Down
3 changes: 3 additions & 0 deletions crates/signal-ops/src/outbound.rs
Original file line number Diff line number Diff line change
Expand Up @@ -516,6 +516,7 @@ impl<S: ServiceStore> SignalOps<S> {
.await
.map_err(send_error)?;

sessions.ensure_finalized()?;
let encoded = waproto::codec::message_to_vec(message);
staged
.put_aux(
Expand Down Expand Up @@ -873,6 +874,7 @@ impl<S: ServiceStore> SignalOps<S> {
)
.await?;
}
sessions.ensure_finalized()?;
let encoded = waproto::codec::message_to_vec(message);
staged
.put_aux(
Expand Down Expand Up @@ -1143,6 +1145,7 @@ impl<S: ServiceStore> SignalOps<S> {
)
.await
.map_err(send_error)?;
sessions.ensure_finalized()?;
staged.commit().await?;
wacore_binary::marshal(&node)
.map_err(|e| OpsError::Send(format!("stanza did not marshal: {e}")))
Expand Down
Loading
Loading