Files
archie/internal/domain/messaging/media.go
T
sam 2965f8354c fix(messaging): read a voice clip's container instead of believing its type
The dashboard upload names its own attachment type, so the check that ran on
it only compared two declarations the sender wrote. A browser can label any
bytes audio/ogg, and the transcriber keys on the attachment type alone, so the
bytes went to the operator's provider regardless.

When the bytes are present the container decides: Ogg, WebM/Matroska, mp4/m4a,
wav, flac and mp3 are the containers a clip is recorded in, and anything else
claimed to be speech is refused before it reaches a transcriber. Magic numbers
rather than http.DetectContentType, which reports application/octet-stream for
the WebM every browser but Safari records.
2026-10-25 20:17:30 +11:00

188 lines
6.3 KiB
Go

package messaging
import (
"fmt"
"mime"
"strings"
)
// MaxInboundAttachmentBytes is the largest attachment carried to the Gateway.
const MaxInboundAttachmentBytes = 20 << 20
// Media types. MediaTypeVoice is recorded speech, which is transcribed;
// MediaTypeAudio is other audio.
const (
MediaTypeImage = "image"
MediaTypeVideo = "video"
MediaTypeAudio = "audio"
MediaTypeDocument = "document"
MediaTypeVoice = "voice"
)
// MediaAttachment describes a file attached to a message. Pointer fields
// distinguish zero from unknown.
type MediaAttachment struct {
// Type is "image", "video", "audio", "voice", or "document".
Type string `json:"type"`
// FileID is the platform-assigned identifier for download APIs.
FileID string `json:"file_id"`
// URL is a direct download URL when available. May be empty for
// platforms that require a download API call.
URL string `json:"url,omitempty"`
// Path is a local file to upload. Exactly one of URL and Path is used for an
// outbound send.
Path string `json:"path,omitempty"`
// MIMEType is the content type (e.g. "image/png", "audio/ogg").
MIMEType string `json:"mime_type,omitempty"`
// FileName is the original file name when known.
FileName string `json:"file_name,omitempty"`
// FileSize is the attachment size in bytes. nil means unknown.
FileSize *int64 `json:"file_size,omitempty"`
// Width is the pixel width for images and video. nil means unknown
// or not applicable.
Width *int `json:"width,omitempty"`
// Height is the pixel height for images and video. nil means unknown
// or not applicable.
Height *int `json:"height,omitempty"`
// Duration is the play time in seconds for audio and video.
Duration *int `json:"duration,omitempty"`
// Raw carries platform-specific fields the common vocabulary does not
// cover, so adapters never need a second attachment type.
Raw map[string]any `json:"raw,omitempty"`
// Data holds the attachment bytes in-process on the inbound path. Never
// persisted.
Data []byte `json:"data,omitempty"`
}
// ValidateInbound refuses an attachment whose declared content type contradicts
// its declared attachment type, whose declared size is over the ceiling, or --
// when the bytes are here and the attachment claims to be speech -- bytes that
// are not in a container audio is recorded in. The declaration decides how the
// file is used: a voice note is transcribed, an image is sent to a model. Only
// speech is read, because it is the one type where every producer uses one of a
// handful of containers and a wrong container means it was never a clip.
func ValidateInbound(att MediaAttachment) error {
fileName := att.FileName
if fileName == "" {
fileName = att.Type
}
switch att.Type {
case MediaTypeImage, MediaTypeVideo, MediaTypeAudio, MediaTypeVoice, MediaTypeDocument:
default:
return fmt.Errorf("media: %s: unknown attachment type %q", fileName, att.Type)
}
for _, size := range []int64{int64(len(att.Data)), int64Of(att.FileSize)} {
if size > MaxInboundAttachmentBytes {
return fmt.Errorf("media: %s is %d bytes, over the %d byte limit", fileName, size, MaxInboundAttachmentBytes)
}
}
if len(att.Data) > 0 && (att.Type == MediaTypeAudio || att.Type == MediaTypeVoice) && sniffAudio(att.Data) == "" {
return fmt.Errorf("media: %s: the bytes are not a recorded clip", fileName)
}
if att.MIMEType == "" {
// A platform adapter may genuinely not know the content type. A caller
// that chose the attachment type itself must supply one; see
// ValidateAuthoredInbound.
return nil
}
mediaType, _, err := mime.ParseMediaType(att.MIMEType)
if err != nil {
return fmt.Errorf("media: %s: %q is not a content type", fileName, att.MIMEType)
}
if !typeCarriesMIME(att.Type, mediaType) {
return fmt.Errorf("media: %s: %q cannot be a %s", fileName, mediaType, att.Type)
}
return nil
}
// typeCarriesMIME reports whether an attachment of this type can hold a file of
// that content type. A document carries anything; the others would be used as
// what they claim to be.
func typeCarriesMIME(attachmentType, mediaType string) bool {
family := mediaType
if slash := strings.IndexByte(family, '/'); slash >= 0 {
family = family[:slash]
}
switch attachmentType {
case MediaTypeImage:
return family == "image"
case MediaTypeVideo:
return family == "video"
case MediaTypeAudio, MediaTypeVoice:
// Ogg is served as application/ogg, and the voice notes browsers and
// platforms record are Ogg, WebM or (Safari) mp4.
return family == "audio" || mediaType == "application/ogg"
default:
return true
}
}
func int64Of(p *int64) int64 {
if p == nil {
return 0
}
return *p
}
// audioMagic are the leading bytes of the containers a clip is recorded in.
var audioMagic = []struct {
at int
magic string
kind string
}{
{0, "OggS", "audio/ogg"},
{0, "\x1a\x45\xdf\xa3", "audio/webm"},
{0, "fLaC", "audio/flac"},
{0, "ID3", "audio/mpeg"},
// An ISO base media file, opened with any of the boxes a writer may lead
// with rather than ftyp first.
{4, "ftyp", "audio/mp4"},
{4, "moov", "audio/mp4"},
{4, "mdat", "audio/mp4"},
{4, "free", "audio/mp4"},
{4, "skip", "audio/mp4"},
{4, "wide", "audio/mp4"},
}
// sniffAudio reports the content type of the container data starts with, or ""
// when the bytes are not in one a voice clip is recorded in. Magic numbers are
// read rather than http.DetectContentType, which answers application/octet-stream
// for the WebM every browser but Safari records.
func sniffAudio(data []byte) string {
for _, m := range audioMagic {
if len(data) >= m.at+len(m.magic) && string(data[m.at:m.at+len(m.magic)]) == m.magic {
return m.kind
}
}
if len(data) >= 12 && string(data[:4]) == "RIFF" && string(data[8:12]) == "WAVE" {
return "audio/wav"
}
// An mp3 with its tag stripped starts on a frame sync.
if len(data) >= 2 && data[0] == 0xFF && data[1]&0xE0 == 0xE0 {
return "audio/mpeg"
}
return ""
}
// ValidateAuthoredInbound is ValidateInbound for an attachment the caller
// described itself, as a browser upload is: its content type is a claim, not an
// observation, so it must be stated. A platform adapter uses ValidateInbound,
// where an unknown content type is not a lie.
func ValidateAuthoredInbound(att MediaAttachment) error {
if att.MIMEType == "" {
return fmt.Errorf("media: %s: no content type", att.Type)
}
return ValidateInbound(att)
}