Documentation
¶
Overview ¶
Package envelope implements the two-layer Messenger wire model.
The outer Relay Envelope is what a Mailbox Relay sees: an opaque mailbox identifier, bounded ciphertext, and the resource fields needed to store and expire it. It carries no sender identity, no conversation identity, and no commercial state.
That is a narrower claim than it sounds. A Relay cannot read a message or resolve the canonical Agent and Conversation it belongs to, and it can still observe and correlate what is left: a stable mailbox identifier, message identifiers, storage tokens, ciphertext sizes, expiry, timing, addresses, and how often each appears. Reducing that residue is mailbox rotation, padding, and batching, none of which exists yet, and the honest description is that the content is closed and the metadata is not.
The inner Messaging Event is what the recipient obtains after decryption. Nothing in this package performs encryption: the cryptographic suite is an M0 freeze decision, and inventing one here is exactly what the architecture forbids.
Index ¶
- Constants
- func AcceptedForStorage(relayEnvelope RelayEnvelope, now time.Time, maxRetention time.Duration) error
- func AdmittedBy(delegation identity.Delegation, event Event) error
- func ClassOf(kind string) (string, bool)
- func ConversationID(raw []byte) (string, error)
- func DeriveEventID(event Event) (string, error)
- func DeviceID(raw []byte) (string, error)
- func EncodeEventJSON(event Event) ([]byte, error)
- func EncodeRelayJSON(relayEnvelope RelayEnvelope) ([]byte, error)
- func EventCanonicalBytes(event Event) ([]byte, error)
- func KnownKinds() []string
- func LocalOnly(kind string) bool
- func MailboxID(raw []byte) (string, error)
- func MessageID(raw []byte) (string, error)
- func PayloadSchemaOf(kind string) (string, bool)
- func RequiresEstablishedDirect(kind string) bool
- func ValidateEvent(event Event) error
- func ValidateRelay(relayEnvelope RelayEnvelope) error
- type Event
- type RelayEnvelope
Constants ¶
const ( // RelaySchema is the strict wire schema identifier. RelaySchema = "tos.messaging.relay-envelope.v1" // MaxCiphertextBytes bounds one stored envelope. MaxCiphertextBytes = 1 << 20 // MinCiphertextBytes rejects an empty or obviously truncated body. MinCiphertextBytes = 32 // MaxStorageTokenBytes bounds the optional opaque storage token. MaxStorageTokenBytes = 256 // MaxAdmissionTokenBytes bounds an opaque recipient admission credential. MaxAdmissionTokenBytes = 256 // MaxEnvelopeLifetimeSeconds bounds how long a Relay may be asked to hold // ciphertext. Retention is a resource commitment, so it is never open ended. MaxEnvelopeLifetimeSeconds = 30 * 24 * 60 * 60 )
const ( // EventSchema is the strict wire schema identifier. EventSchema = "tos.messaging.event.v2" // MaxContentBytes bounds one event body. MaxContentBytes = 128 << 10 // MaxCausalParents bounds the causal reference set. MaxCausalParents = 16 // MaxAttachmentReferences bounds the attachments one event may reference. MaxAttachmentReferences = 16 // MaxRenderingBytes bounds the optional human presentation. MaxRenderingBytes = 4 << 10 )
Variables ¶
This section is empty.
Functions ¶
func AcceptedForStorage ¶
func AcceptedForStorage(relayEnvelope RelayEnvelope, now time.Time, maxRetention time.Duration) error
AcceptedForStorage is the check a Relay runs before it commits resources: a well-formed envelope, an expiry in the future, and a retention request within the operator's bound.
func AdmittedBy ¶
func AdmittedBy(delegation identity.Delegation, event Event) error
AdmittedBy reports whether a delegation grants the sender's endpoint the class of this event, and that the event was produced by the delegated endpoint of the delegated Agent in the delegated network.
This is a scope check only. It is not a substitute for session authentication, inbox policy, or the execution gate.
func ClassOf ¶
ClassOf returns the delegated class of an event kind. An unknown kind has no class and therefore no scope.
func ConversationID ¶
ConversationID formats a conversation identifier.
func DeriveEventID ¶
DeriveEventID content-addresses an event. Two peers that hold the same event compute the same identifier, and no peer can present different content under an identifier another peer already committed.
func EncodeEventJSON ¶
EncodeEventJSON returns the plaintext transport representation. Callers encrypt the result; this package never places it on a wire itself.
func EncodeRelayJSON ¶
func EncodeRelayJSON(relayEnvelope RelayEnvelope) ([]byte, error)
EncodeRelayJSON returns the transport representation of a valid envelope.
func EventCanonicalBytes ¶
EventCanonicalBytes returns the preimage the Event ID commits to. The Event ID itself is excluded, because it is derived from this preimage.
func LocalOnly ¶
LocalOnly reports whether a kind may only arrive over the owner's own local interface.
A local-only kind carries authority rather than information, so it is not something a remote party may express. Callers on the network path refuse it outright rather than evaluating it and deciding it is not allowed.
func MailboxID ¶
MailboxID formats a recipient-generated opaque mailbox identifier. The recipient chooses the bytes; the Relay only ever sees the formatted value.
func MessageID ¶
MessageID formats a per-envelope identifier used for Relay-level deduplication. It is not the application Event ID and must never be treated as one: a Relay can forge it, an Event ID it cannot.
func PayloadSchemaOf ¶
PayloadSchemaOf returns the structured payload schema a kind carries.
The schema comes from the codec that actually parses the body, not from a second table kept in step by hand. A kind whose schema was declared in one place and implemented in another would eventually declare a contract nothing enforced.
func RequiresEstablishedDirect ¶
RequiresEstablishedDirect identifies private application events that are forbidden in first contact and rooms. Their authority comes from an already authenticated direct E2EE conversation.
func ValidateEvent ¶
ValidateEvent enforces every structural rule and re-derives the Event ID.
func ValidateRelay ¶
func ValidateRelay(relayEnvelope RelayEnvelope) error
ValidateRelay enforces every structural rule.
Types ¶
type Event ¶
type Event struct {
Network *nativev1.NetworkDomain
ConversationID string
EventID string
SenderAgentID string
SenderEndpointID string
SenderDeviceID string
RoomID string
ThreadID string
ReplyToEventID string
CausalParents []string
CreatedAtUnix uint64
ExpiresAtUnix uint64
Kind string
// PayloadSchema names the structure of Content. It is fixed by the kind,
// and carried explicitly so a decoder is reading a declared shape rather
// than guessing one from a name.
PayloadSchema string
IdempotencyKey string
// Content is the structured payload. It is what automation reads.
Content []byte
// Rendering is an optional human presentation of the same event.
//
// It is presentation and never input. Where the two disagree the
// difference is not a preference to resolve: a caller that let a model
// choose which one to believe would have made the rendering authoritative
// by another route.
Rendering string
AttachmentReferences []string
ServiceBinding string
}
Event is the inner typed object obtained after decryption.
Authenticity comes from the end-to-end encrypted session, not from a field in this struct. A high-value control event may additionally carry an independently verifiable signature, which is a separate profile.
func DecodeEventJSON ¶
DecodeEventJSON rejects unknown fields, trailing data, unrecognised event kinds, and any event whose identifier does not match its content.
func DecodeEventJSONForwardCompatible ¶
DecodeEventJSONForwardCompatible additionally admits an event kind this build does not recognise, for a caller whose policy explicitly allows forward compatibility.
A forward-compatible event has no delegated class, so it must never be interpreted as a tool call, an approval, or a payment. It may be stored and displayed as an unknown event and nothing more.
type RelayEnvelope ¶
type RelayEnvelope struct {
OpaqueMailboxID string
MessageID string
Ciphertext []byte
ExpiresAtUnix uint64
StorageToken string
AdmissionToken string
}
RelayEnvelope is the outer object a Relay stores. It is not an Agent signature, a payment receipt, or proof that an application accepted anything.
func DecodeRelayJSON ¶
func DecodeRelayJSON(raw []byte) (RelayEnvelope, error)
DecodeRelayJSON rejects unknown fields, trailing data, and a declared size that disagrees with the body. A size field that is trusted over the body it describes is a parser-confusion bug waiting to happen, so the two must agree exactly.