Encrypt annotation data payloads on encrypted channels

[SimonWoolf]

Annotation had no encrypt() method at all, so annotation data was published in plaintext even when the channel had a cipher configured — while Message (ably/types/message.py:235) and PresenceMessage (ably/types/presence.py:123) were correctly encrypted before serialisation at their publish sites (ably/rest/channel.py:80, ably/realtime/channel.py:415).

The REST get() path compounded it by hardcoding cipher=None when building its response handler, so it could not have decrypted an encrypted annotation either. The realtime receive path (ably/realtime/channel.py:768) already passed cipher=self.cipher correctly, so it was only the REST direction that was broken.

Changes

• Add Annotation.encrypt(), mirroring Message.encrypt().
• Call it from both publish paths (rest/annotations.py, realtime/annotations.py), guarded on channel.cipher like the message paths are.
• Pass the channel's cipher when decoding REST get() responses.
• Remove three docstrings asserting annotations are not encrypted (see below).

One deliberate difference from Message.encrypt(): annotations very commonly carry no data at all — a reaction is fully described by its name, and every existing annotation test passes data=None. Message.encrypt() would raise TypeError: Unexpected object type <class 'NoneType'> from TypedBuffer.from_obj() on that input; it just never gets called that way in practice. Annotation.encrypt() returns early instead. Worth noting Message.encrypt() has the same latent flaw if it is ever called with data=None, but I have left it alone.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Annotation payloads are now encrypted when channels are configured for encryption.
  • Encrypted annotations sent through realtime and REST APIs can be decrypted when received.
  • Supports secure encryption for text, dictionary, list, and binary annotation data.

• Bug Fixes

  • Improved handling of annotations with missing or already encrypted data.
  • Preserved encryption metadata when encrypted annotations are decoded without a configured cipher.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c24f254d-7e97-401e-85d4-c225465241a5

📥 Commits

Reviewing files that changed from the base of the PR and between 1c2cd64 and f973365.

📒 Files selected for processing (4)

• ably/realtime/annotations.py
• ably/rest/annotations.py
• ably/types/annotation.py
• test/unit/annotation_test.py

Disabled knowledge base sources:

• Jira integration is disabled

You can enable these sources in your CodeRabbit configuration.

---

Walkthrough

Annotation payloads can now be encrypted for REST and realtime channels with ciphers. Responses pass the channel cipher for decryption, and unit tests cover supported payloads, idempotency, missing data, and cipher-less decoding.

Changes

Annotation encryption flow

Layer / File(s)	Summary
Annotation encryption contract ably/types/annotation.py	Adds Annotation.encrypt() to encrypt string, dictionary, and list payloads into CipherData, while preserving encoding hints and avoiding repeated encryption.
REST and realtime transport integration ably/rest/annotations.py, ably/realtime/annotations.py	Encrypts annotations before serialization and passes the configured channel cipher to REST response handling.
Encryption behavior validation test/unit/annotation_test.py	Tests encrypted round trips, binary payload modes, missing data, idempotency, and decoding without a cipher.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant RestAnnotations
  participant RealtimeAnnotations
  participant Annotation
  participant ChannelCipher
  RestAnnotations->>Annotation: encrypt annotation payload
  Annotation->>ChannelCipher: encrypt typed data
  ChannelCipher-->>Annotation: return CipherData
  RestAnnotations->>RestAnnotations: serialize encrypted annotation
  RealtimeAnnotations->>Annotation: encrypt annotation payload
  Annotation->>ChannelCipher: encrypt typed data
  ChannelCipher-->>Annotation: return CipherData
  RealtimeAnnotations->>RealtimeAnnotations: serialize encrypted annotation

Loading

Possibly related PRs

• ably/ably-python#667: Introduced the annotation modules and classes extended by these encryption changes.

Poem

A bunny hops where ciphertext gleams,
Payloads now travel through encrypted streams.
REST and realtime guard the way,
While tests make sure the plaintext stays.
With cipher in hand, responses bloom—
Safe little annotations leave the room!

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Fix failing CI checks

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch encrypted-annotation-data

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[owenpearson]

looks good! there are ci failures on every python version but they seem unrelated (all push admin timeouts)