envelope

package
v0.0.0-...-1a05352 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 22, 2026 License: GPL-3.0, GPL-3.0 Imports: 12 Imported by: 0

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

View Source
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
)
View Source
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

func ClassOf(kind string) (string, bool)

ClassOf returns the delegated class of an event kind. An unknown kind has no class and therefore no scope.

func ConversationID

func ConversationID(raw []byte) (string, error)

ConversationID formats a conversation identifier.

func DeriveEventID

func DeriveEventID(event Event) (string, error)

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 DeviceID

func DeviceID(raw []byte) (string, error)

DeviceID formats a device identifier.

func EncodeEventJSON

func EncodeEventJSON(event Event) ([]byte, error)

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

func EventCanonicalBytes(event Event) ([]byte, error)

EventCanonicalBytes returns the preimage the Event ID commits to. The Event ID itself is excluded, because it is derived from this preimage.

func KnownKinds

func KnownKinds() []string

KnownKinds returns the recognised event kinds.

func LocalOnly

func LocalOnly(kind string) bool

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

func MailboxID(raw []byte) (string, error)

MailboxID formats a recipient-generated opaque mailbox identifier. The recipient chooses the bytes; the Relay only ever sees the formatted value.

func MessageID

func MessageID(raw []byte) (string, error)

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

func PayloadSchemaOf(kind string) (string, bool)

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

func RequiresEstablishedDirect(kind string) bool

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

func ValidateEvent(event Event) error

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

func DecodeEventJSON(raw []byte) (Event, error)

DecodeEventJSON rejects unknown fields, trailing data, unrecognised event kinds, and any event whose identifier does not match its content.

func DecodeEventJSONForwardCompatible

func DecodeEventJSONForwardCompatible(raw []byte) (Event, error)

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.

func NewEvent

func NewEvent(event Event) (Event, error)

NewEvent completes an event by filling the schema its kind fixes and deriving its identifier.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL