Just doing the spec right now:

> The extra DBus channel interface is implemented using GDBus
> so it needs to be exported on a different bus name.

Ugh. Can we not do strange hacks like this, please? Either use the extensions mechanism, or save it for 1.0.

+ <interface name="im.telepathy.v1.Channel.Interface.OTR1"
+ tp:causes-havoc="experimental">
+ <tp:added version="Gabble 0.UNRELEASED">(Gabble-specific)</tp:added>

If doing this in 0.x, please use o.fd.Channel.Interface.OTR1 and add it to telepathy-spec (OK to go via extensions/ until we do the spec -> tp-glib dance, though).

In 1.0, certainly add it to the spec.

+ A simple D-Bus API <a
+ href="https://otr.cypherpunks.ca/">Off The Record</a>.

"... API for <a..."

+ <p>The current trust level of this channel:
+ 0=TRUST_NOT_PRIVATE, 1=TRUST_UNVERIFIED, 2=TRUST_PRIVATE,
+ 3=TRUST_FINISHED</p>

This deserves a <tp:enum> and documentation.

I assume the meanings go something like this:

TRUST_NOT_PRIVATE: not using OTR at all? (Can we also see this when using OTR but something has gone wrong?)
(o.fd.Channel.I.Securable.Encrypted=FALSE, o.fd.Channel.I.Securable.Verified=FALSE)

TRUST_UNVERIFIED: the channel is encrypted, but you might be talking to a man-in-the-middle instead of the peer you expected. (o.fd.Channel.I.Securable.Encrypted=TRUE, o.fd.Channel.I.Securable.Verified=FALSE)

TRUST_PRIVATE: the channel is encrypted, and the user has indicated that the peer's key fingerprint is trusted to belong to that peer.
(o.fd.Channel.I.Securable.Encrypted=TRUE, o.fd.Channel.I.Securable.Verified=TRUE)

TRUST_FINISHED: this channel is over, nothing more should be sent or received on it.
(o.fd.Channel.I.Securable.Encrypted and o.fd.Channel.I.Securable.Verified keep their previous values?)

What are the possible state transitions? I assume "can only increase"?

+ type="(say)" access="read">
+ <p>User's current fingerprint. The first element is a human readable
+ fingerprint that can be displayed to the user so he can communicate it
+ to the other end by other means so he can trust it. The 2nd element is
+ the fingerprint raw data.</p>

Are these literally the hex and binary versions of the same digest, or do they have different information content? (Or is the string version some OTR-specific thing that is easier to transcribe than hex?)

+ <property name="RemoteFingerprint"
+ tp:name-for-bindings="Fingerprint"
+ type="(say)" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">

What value does this take when the channel is not using OTR? ('', [])?

When we're in the UNVERIFIED state, am I right in thinking that we are cryptographically guaranteed to have the right fingerprint for who we're talking to, but the thing that is unverified is that the fingerprint belongs to the person we wanted to talk to? (i.e. if we're talking to a man-in-the-middle, this would be the fingerprint of the man-in-the-middle's key, right?)

Is it possible for this to change? (Presumably from ('', []) to non-empty, at the same time that the trust changes to UNVERIFIED or PRIVATE?)

After this has become non-empty, can it change further? (I would hope not.)

I think it would also be useful to spec that one of the forms of the remote fingerprint will appear in the message header (0'th part) of each individual message, perhaps { "otr-remote-fingerprint": a string }. That would make it easy for someone to do either of these things in a race-condition-free way:

* record in the Logger that the messages were encrypted/verified
* give the Logger a configuration setting "[ ] do not log OTR messages"
  (which it would recognize by seeing that they have an OTR remote fingerprint