envelope

const (
	FieldAlgVersion = "alg_version"
	FieldBody       = "body"
	FieldFromAgent  = "from_agent"
	FieldKeyEpoch   = "key_epoch"
	FieldNonce      = "nonce"
	FieldRoom       = "room"
	FieldSeq        = "seq"
	FieldToAgent    = "to_agent"
	FieldTS         = "ts"

	// FieldFromClass, FieldKind, FieldVouchesFor, FieldGateRef are the OPTIONAL
	// human-principal signed fields (S3). Each is OMITTED when absent (absent !=
	// null in JCS), exactly like room/to_agent — never emitted as a null value.
	FieldFromClass  = "from_class"
	FieldKind       = "kind"
	FieldVouchesFor = "vouches_for"
	FieldGateRef    = "gate_ref"

	// FieldSig and FieldFromPubKey are TRANSPORT field names (NOT in the signed
	// subset). They are the keys of the {sig, from_pubkey, key_epoch} result the
	// caller stamps into the wire envelope after signing.
	FieldSig        = "sig"
	FieldFromPubKey = "from_pubkey"
)

const (
	// AlgVersion is the pinned signing algorithm version. CanonicalizeEnvelope
	// rejects any other value (anti-downgrade).
	AlgVersion = 1

	// MaxSafeInt is the inclusive upper bound for the signed integer fields
	// (alg_version, key_epoch, seq, ts). It is 2^53 — the largest integer JCS
	// (which renders numbers as IEEE-754 doubles) round-trips without precision
	// loss. Mirrors registry.MaxSafeEpoch / identity's maxSafeInteger.
	MaxSafeInt = int64(1) << 53
	// MinKeyEpoch is the inclusive lower bound for key_epoch (same anti-rollback
	// floor as the registry: a zero/negative epoch is rejected).
	MinKeyEpoch = 1
)

const (
	// FromClassAgent | FromClassBridge | FromClassHuman are the valid from_class
	// values. FromClassAgent is also the registry's default effective class
	// (registry.ClassAgent).
	FromClassAgent  = "agent"
	FromClassBridge = "bridge"
	FromClassHuman  = "human"

	// KindChat | KindApproval are the valid kind values. An absent kind is treated
	// as chat at verify (no effect), but a PRESENT kind must be one of these.
	KindChat     = "chat"
	KindApproval = "approval"
)

const (
	// ErrAlgVersion is returned when alg_version != AlgVersion (anti-downgrade).
	ErrAlgVersion = "envelope: alg_version must be 1 (anti-downgrade)"
	// ErrIntRange is returned when alg_version, seq, or ts is outside [0, 2^53].
	ErrIntRange = "envelope: integer field out of range [0, 2^53]"
	// ErrKeyEpochRange is returned when key_epoch is outside [1, 2^53].
	ErrKeyEpochRange = "envelope: key_epoch out of range [1, 2^53]"
	// ErrBodyUTF8 is returned when body is not valid UTF-8.
	ErrBodyUTF8 = "envelope: body is not valid UTF-8"
	// ErrBodyNotNFC is returned when body is not Unicode NFC (no silent normalize).
	ErrBodyNotNFC = "envelope: body must be Unicode NFC-normalized"
	// ErrNonceASCII is returned when nonce is not ASCII.
	ErrNonceASCII = "envelope: nonce must be ASCII"
	// ErrNonceEmpty is returned when nonce is empty.
	ErrNonceEmpty = "envelope: nonce must not be empty"
	// ErrFromAgentEmpty is returned when from_agent is empty.
	ErrFromAgentEmpty = "envelope: from_agent must not be empty"
	// ErrRoutingExactlyOne is returned when NOT exactly one of room|to_agent is
	// present (both set, or neither set). Absent != null is load-bearing in JCS.
	ErrRoutingExactlyOne = "envelope: exactly one of room or to_agent must be present"

	// ErrFieldNotUTF8 is returned when a present human-principal string field
	// (from_class, kind, vouches_for, gate_ref) is not valid UTF-8.
	ErrFieldNotUTF8 = "envelope: signed string field is not valid UTF-8"
	// ErrFieldNotNFC is returned when a present human-principal string field is
	// not Unicode NFC (no silent normalize — same discipline as body).
	ErrFieldNotNFC = "envelope: signed string field must be Unicode NFC-normalized"
	// ErrFromClassInvalid is returned when a present from_class is not one of
	// agent|bridge|human.
	ErrFromClassInvalid = "envelope: from_class must be agent, bridge, or human"
	// ErrKindInvalid is returned when a present kind is not one of chat|approval.
	ErrKindInvalid = "envelope: kind must be chat or approval"
	// ErrBridgeNeedsVouch is returned when from_class=bridge but vouches_for is
	// absent (a bridge MUST name whom it vouches for).
	ErrBridgeNeedsVouch = "envelope: from_class=bridge requires vouches_for"
	// ErrVouchNeedsBridge is returned when vouches_for is present but from_class
	// is not bridge (only a bridge may vouch).
	ErrVouchNeedsBridge = "envelope: vouches_for requires from_class=bridge"
	// ErrApprovalNeedsGateRef is returned when kind=approval but gate_ref is
	// absent (an approval MUST reference the gate it approves).
	ErrApprovalNeedsGateRef = "envelope: kind=approval requires gate_ref"
	// ErrGateRefNeedsApproval is returned when gate_ref is present but kind is not
	// approval (gate_ref is only meaningful on an approval).
	ErrGateRefNeedsApproval = "envelope: gate_ref requires kind=approval"

	// ErrVerifyClassMismatch is returned by VerifyEnvelope when an envelope's
	// PRESENT from_class claim does not equal the resolved binding's effective
	// class. The signature authenticates the claim; only the registry binding
	// AUTHORIZES it (authenticated != authorized — fail closed).
	ErrVerifyClassMismatch = "envelope: from_class claim does not match the registry binding class"
	// ErrVerifyVouchNotAllowed is returned by VerifyEnvelope when a bridge's
	// vouches_for is not in the binding's VouchAllowlist (empty allowlist ⇒ every
	// vouch rejected).
	ErrVerifyVouchNotAllowed = "envelope: vouches_for is not in the binding's vouch allowlist"
)