jochen
a76b0742ff
messenger's content rule (ADR 0253 §3) refuses any message carrying a mail address, so mail_send's ask never reached the operator: no send could ever be approved. A recipient that is one of the operator's own mesh-mail accounts is now named by that account's name; any other loses its address and host; the subject and body's first lines have every address and link masked before they reach the ask. The mail itself is sent unchanged. Tests run messenger's real content rule against the asks mail_send builds (content.go copied verbatim as content_test.go, pinned byte-identical by copies_test.go, since messenger's package main cannot be imported from another module).
523 lines
19 KiB
Go
523 lines
19 KiB
Go
package main
|
|
|
|
// The module's tools (novox/hq ADR 0359 §5, ADR 0361 §2): mail_accounts, mail_search, mail_read, mail_health,
|
|
// mail_send and mail_send_status. Who calls is the runtime's word (stdio.CallerOf), never an argument; a caller
|
|
// reads an account's mail, or sends from it, only when the trusted setting `grants` names it for that account (§4).
|
|
// Nothing here writes to a mailbox; mail_send writes nothing itself either (send.go) — it only ever reaches the
|
|
// account's outgoing server on the operator's own Approve.
|
|
|
|
import (
|
|
"context"
|
|
"encoding/base64"
|
|
"errors"
|
|
"fmt"
|
|
"strings"
|
|
"time"
|
|
|
|
stdio "git.novox.be/novox/mesh-sdk/go"
|
|
)
|
|
|
|
// Tool names, as the manifest declares them.
|
|
const (
|
|
AccountsTool = "mail_accounts"
|
|
SearchTool = "mail_search"
|
|
ReadTool = "mail_read"
|
|
SendTool = "mail_send"
|
|
SendStatusTool = "mail_send_status"
|
|
)
|
|
|
|
// Seat tool names: mesh-mail claims the mail-store seat (novox/hq ADR 0378 §2, §3; issue 800 part A) and serves
|
|
// its verbs through the same handlers as the mail_* tools above — the seat's name is the one a caller grants
|
|
// reach the same account's mail through, whichever name it calls.
|
|
const (
|
|
SeatAccountsTool = "mail-store.accounts"
|
|
SeatSearchTool = "mail-store.search"
|
|
SeatReadTool = "mail-store.read"
|
|
SeatSendTool = "mail-store.send"
|
|
)
|
|
|
|
// Bounds of what a tool answers.
|
|
const (
|
|
MostResults = 50
|
|
MostQuery = 200
|
|
MostBodyAnswered = 64 << 10
|
|
MostAttachment = 8 << 20
|
|
)
|
|
|
|
// Bundle is what the tools reach: the settings, the index, the attachment store, and — for mail_send — the
|
|
// operator channel, the `sends` state and the outgoing dialer. The last three are nil outside a test: the real
|
|
// bus and dialer (sdkAskBus, keptSends, DialSMTP) are used lazily, so building a Bundle for the read-only tools
|
|
// never needs them.
|
|
type Bundle struct {
|
|
Env Env
|
|
Index func(ctx context.Context) (Store, error)
|
|
Objects func() (Objects, error)
|
|
Caller func(args map[string]any) string
|
|
Now func() time.Time
|
|
|
|
Asks AskBus
|
|
Sends SendStore
|
|
Dial SMTPDialer
|
|
Logf func(format string, a ...any)
|
|
}
|
|
|
|
func (b *Bundle) now() time.Time {
|
|
if b.Now != nil {
|
|
return b.Now()
|
|
}
|
|
return time.Now()
|
|
}
|
|
|
|
// settings are the accounts and the grants. A grants setting that cannot be read grants nothing, and its reason is
|
|
// kept, so a refusal says why rather than only that the caller is not granted.
|
|
func (b *Bundle) settings() ([]Account, access, error) {
|
|
accounts, err := ReadAccounts(b.Env.Accounts)
|
|
if err != nil {
|
|
return nil, access{}, err
|
|
}
|
|
grants, err := ReadGrants(b.Env.Grants)
|
|
if err != nil {
|
|
return accounts, access{grants: Grants{}, unread: err}, nil
|
|
}
|
|
return accounts, access{grants: grants}, nil
|
|
}
|
|
|
|
// access is the grants as read, and why they could not be, when they could not.
|
|
type access struct {
|
|
grants Grants
|
|
unread error
|
|
}
|
|
|
|
func (a access) Allows(caller, account string) bool { return a.grants.Allows(caller, account) }
|
|
|
|
func (a access) Granted(caller string, accounts []Account) []string {
|
|
return a.grants.Granted(caller, accounts)
|
|
}
|
|
|
|
// refuse is the refusal of a caller for an account, saying why: the grants unread, or the caller not in them.
|
|
func (a access) refuse(caller, account string) error {
|
|
if a.unread != nil {
|
|
return fmt.Errorf("refused: the setting grants cannot be read, so it grants nobody: %v", a.unread)
|
|
}
|
|
return refused(caller, account)
|
|
}
|
|
|
|
// Tools are the module's tools.
|
|
func (b *Bundle) Tools() []stdio.Tool {
|
|
return []stdio.Tool{
|
|
{Name: AccountsTool,
|
|
Description: "The operator's mail accounts you are granted, each with its kind, its address, its state (syncing, " +
|
|
"current, waits-for-sign-in or failing, and why), when its server last answered, when it was last brought up to " +
|
|
"date, and its folders with how many messages each holds. An account you are not granted is not listed, and " +
|
|
"nothing of it is said. How the module as a whole is, is mail_health's to say. Read-only.",
|
|
Input: schema(nil, map[string]any{}),
|
|
Run: b.accountsTool},
|
|
{Name: SearchTool,
|
|
Description: "Search the mail of the accounts you are granted: every word of the query must be in the subject, the " +
|
|
"text, a sender or a recipient. Answers the newest first, at most 50: account, folder, uid, message id, date, " +
|
|
"sender, recipients, subject, size, flags and attachment references, never a body. Refused for an account you " +
|
|
"are not granted, and when you are granted none. Read-only.",
|
|
Input: schema([]string{"query"}, map[string]any{
|
|
"query": text("the words to find, at most 200 characters"),
|
|
"account": text("one account by its name in mail_accounts; every account you are granted when left out"),
|
|
"folder": text("one folder, such as INBOX; every folder when left out"),
|
|
"limit": integer("how many to answer, at most 50 (20 when left out)"),
|
|
}),
|
|
Run: b.searchTool},
|
|
{Name: ReadTool,
|
|
Description: "Read one message of an account you are granted, as an event or mail_search names it (account, folder, " +
|
|
"uid): its metadata and its text (the plain part, or the HTML part as text, at most 64 KiB here). With " +
|
|
"attachment (its key, the SHA-256 the message's references name), that one attachment's bytes, base64, at most " +
|
|
"8 MiB. Refused for an account you are not granted. Never marks a message seen. Read-only.",
|
|
Input: schema([]string{"account", "folder", "uid"}, map[string]any{
|
|
"account": text("the account, by its name in mail_accounts"),
|
|
"folder": text("the folder, such as INBOX"),
|
|
"uid": integer("the message's uid in that folder"),
|
|
"attachment": text("an attachment's key, the SHA-256 the message's references name, to answer its bytes"),
|
|
}),
|
|
Run: b.readTool},
|
|
{Name: HealthTool,
|
|
Description: "How mesh-mail is, as its watch last saw it: healthy when every account's server answered within five " +
|
|
"minutes; unhealthy, naming the account and why, when a connection is down or its IDLE on the inbox went silent; " +
|
|
"waits, naming the account's password, while the operator has not given it at the desk.",
|
|
Input: schema(nil, map[string]any{}),
|
|
Run: func(map[string]any) (any, error) { return ReadStatus(b.Env.Status, b.now()), nil }},
|
|
{Name: SendTool,
|
|
Description: "Send mail from an account you are granted (the same check as mail_read, novox/hq ADR 0361 §2). It " +
|
|
"sends nothing itself: it raises an ask on the operator channel — the account, the recipients, the subject and " +
|
|
"the first lines of the body — and answers at once with the ask's id. The mail reaches the account's outgoing " +
|
|
"server only once the operator's Approve comes back on a channel that proves who answered, and once; on " +
|
|
"Decline, or no answer before it expires, nothing is sent. Refused for an account you are not granted, or one " +
|
|
"with no outgoing server. mail_send_status, with this id, says where it stands.",
|
|
Input: schema([]string{"account", "to", "subject", "body"}, map[string]any{
|
|
"account": text("the account to send from, by its name in mail_accounts"),
|
|
"to": map[string]any{"type": "array", "items": map[string]any{"type": "string"},
|
|
"description": "the recipients' mail addresses, at most 20"},
|
|
"subject": text("the message's subject, at most 200 characters"),
|
|
"body": text("the message's plain-text body"),
|
|
}),
|
|
Run: b.sendTool},
|
|
{Name: SendStatusTool,
|
|
Description: "Where a send asked with mail_send stands, by its ask id: waiting for the operator, sent, declined, " +
|
|
"ended without a choice (expired, refused, cancelled), or not proven. Read from the router's own record, held " +
|
|
"to the request mail_send asked (so a warrant for another request, or one changed since, sends nothing here).",
|
|
Input: schema([]string{"id"}, map[string]any{"id": text("the ask id mail_send gave")}),
|
|
Run: b.sendStatusTool},
|
|
{Name: SeatAccountsTool,
|
|
Description: "The mail-store seat's accounts verb (novox/hq ADR 0378 §2): the same as mail_accounts.",
|
|
Input: schema(nil, map[string]any{}),
|
|
Run: b.accountsTool},
|
|
{Name: SeatSearchTool,
|
|
Description: "The mail-store seat's search verb (novox/hq ADR 0378 §2): the same as mail_search.",
|
|
Input: schema([]string{"query"}, map[string]any{
|
|
"query": text("the words to find, at most 200 characters"),
|
|
"account": text("one account by its name in mail_accounts; every account you are granted when left out"),
|
|
"folder": text("one folder, such as INBOX; every folder when left out"),
|
|
"limit": integer("how many to answer, at most 50 (20 when left out)"),
|
|
}),
|
|
Run: b.searchTool},
|
|
{Name: SeatReadTool,
|
|
Description: "The mail-store seat's read verb (novox/hq ADR 0378 §2): the same as mail_read.",
|
|
Input: schema([]string{"account", "folder", "uid"}, map[string]any{
|
|
"account": text("the account, by its name in mail_accounts"),
|
|
"folder": text("the folder, such as INBOX"),
|
|
"uid": integer("the message's uid in that folder"),
|
|
"attachment": text("an attachment's key, the SHA-256 the message's references name, to answer its bytes"),
|
|
}),
|
|
Run: b.readTool},
|
|
{Name: SeatSendTool,
|
|
Description: "The mail-store seat's send verb (novox/hq ADR 0378 §2): the same as mail_send.",
|
|
Input: schema([]string{"account", "to", "subject", "body"}, map[string]any{
|
|
"account": text("the account to send from, by its name in mail_accounts"),
|
|
"to": map[string]any{"type": "array", "items": map[string]any{"type": "string"},
|
|
"description": "the recipients' mail addresses, at most 20"},
|
|
"subject": text("the message's subject, at most 200 characters"),
|
|
"body": text("the message's plain-text body"),
|
|
}),
|
|
Run: b.sendTool},
|
|
}
|
|
}
|
|
|
|
func (b *Bundle) caller(args map[string]any) string {
|
|
if b.Caller != nil {
|
|
return b.Caller(args)
|
|
}
|
|
return stdio.CallerOf(args)
|
|
}
|
|
|
|
func (b *Bundle) accountsTool(args map[string]any) (any, error) {
|
|
if err := only(args); err != nil {
|
|
return nil, err
|
|
}
|
|
accounts, grants, err := b.settings()
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
|
|
defer cancel()
|
|
st, err := b.Index(ctx)
|
|
if err != nil {
|
|
return nil, fmt.Errorf("the index cannot be reached: %v", err)
|
|
}
|
|
states, err := st.States(ctx)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
caller := b.caller(args)
|
|
out := []map[string]any{}
|
|
for _, a := range accounts {
|
|
// Only the accounts the caller is granted: of any other it learns nothing, not even that it exists.
|
|
if !grants.Allows(caller, a.Name) {
|
|
continue
|
|
}
|
|
entry := map[string]any{"account": a.Name, "kind": a.Kind, "address": a.Address}
|
|
if s, ok := states[a.Name]; ok {
|
|
entry["state"], entry["why"] = s.State, s.Why
|
|
if !s.Heard.IsZero() {
|
|
entry["heard"] = s.Heard.UTC().Format(time.RFC3339)
|
|
}
|
|
if !s.Synced.IsZero() {
|
|
entry["synced"] = s.Synced.UTC().Format(time.RFC3339)
|
|
}
|
|
} else {
|
|
entry["state"], entry["why"] = "unknown", "its keeper has said nothing of it yet"
|
|
}
|
|
folders, err := st.Folders(ctx, a.Name)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
entry["folders"] = folders
|
|
out = append(out, entry)
|
|
}
|
|
answer := map[string]any{"accounts": out, "caller": caller}
|
|
if grants.unread != nil {
|
|
answer["why"] = "the setting grants cannot be read, so it grants nobody: " + grants.unread.Error()
|
|
}
|
|
return answer, nil
|
|
}
|
|
|
|
func (b *Bundle) searchTool(args map[string]any) (any, error) {
|
|
if err := only(args, "query", "account", "folder", "limit"); err != nil {
|
|
return nil, err
|
|
}
|
|
query, _ := args["query"].(string)
|
|
if strings.TrimSpace(query) == "" || len(query) > MostQuery {
|
|
return nil, fmt.Errorf("%s needs a query of 1 to %d characters", SearchTool, MostQuery)
|
|
}
|
|
account, _ := args["account"].(string)
|
|
folder, _ := args["folder"].(string)
|
|
limit, err := number(args, "limit", 20)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
if limit < 1 || limit > MostResults {
|
|
return nil, fmt.Errorf("limit is 1 to %d", MostResults)
|
|
}
|
|
accounts, grants, err := b.settings()
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
caller := b.caller(args)
|
|
granted := grants.Granted(caller, accounts)
|
|
if account != "" {
|
|
if !grants.Allows(caller, account) {
|
|
return nil, grants.refuse(caller, account)
|
|
}
|
|
granted = []string{account}
|
|
}
|
|
if len(granted) == 0 {
|
|
if grants.unread != nil {
|
|
return nil, grants.refuse(caller, "")
|
|
}
|
|
return nil, fmt.Errorf("refused: %s is granted no mail account; the operator grants one through the setting grants", caller)
|
|
}
|
|
ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
|
|
defer cancel()
|
|
st, err := b.Index(ctx)
|
|
if err != nil {
|
|
return nil, fmt.Errorf("the index cannot be reached: %v", err)
|
|
}
|
|
found, err := st.Search(ctx, Query{Text: query, Accounts: granted, Folder: folder, Limit: limit})
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
out := make([]map[string]any, 0, len(found))
|
|
for _, m := range found {
|
|
out = append(out, metadata(m))
|
|
}
|
|
return map[string]any{"searched": granted, "found": out}, nil
|
|
}
|
|
|
|
func (b *Bundle) readTool(args map[string]any) (any, error) {
|
|
if err := only(args, "account", "folder", "uid", "attachment"); err != nil {
|
|
return nil, err
|
|
}
|
|
account, _ := args["account"].(string)
|
|
folder, _ := args["folder"].(string)
|
|
attachment, _ := args["attachment"].(string)
|
|
uid, err := number(args, "uid", 0)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
if account == "" || folder == "" || uid <= 0 {
|
|
return nil, fmt.Errorf("%s needs an account, a folder and a uid", ReadTool)
|
|
}
|
|
_, grants, err := b.settings()
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
caller := b.caller(args)
|
|
if !grants.Allows(caller, account) {
|
|
return nil, grants.refuse(caller, account)
|
|
}
|
|
ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
|
|
defer cancel()
|
|
st, err := b.Index(ctx)
|
|
if err != nil {
|
|
return nil, fmt.Errorf("the index cannot be reached: %v", err)
|
|
}
|
|
m, ok, err := st.Get(ctx, account, folder, uint32(uid))
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
if !ok {
|
|
return nil, fmt.Errorf("the account %s holds no message %d in %s", account, uid, folder)
|
|
}
|
|
if attachment != "" {
|
|
var ref *AttachmentRef
|
|
for i := range m.Attachments {
|
|
if m.Attachments[i].Key == attachment {
|
|
ref = &m.Attachments[i]
|
|
}
|
|
}
|
|
if ref == nil {
|
|
return nil, fmt.Errorf("the message names no attachment %s", attachment)
|
|
}
|
|
if ref.Size > MostAttachment {
|
|
return nil, fmt.Errorf("the attachment %s is %d bytes, more than the %d this tool answers", ref.Name, ref.Size, MostAttachment)
|
|
}
|
|
o, err := b.Objects()
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
data, err := o.Get(ctx, ref.Key)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
return map[string]any{"attachment": ref, "base64": base64.StdEncoding.EncodeToString(data)}, nil
|
|
}
|
|
out := metadata(m)
|
|
body := m.Body
|
|
if len(body) > MostBodyAnswered {
|
|
body = strings.ToValidUTF8(body[:MostBodyAnswered], "") + "\n[cut at 64 KiB]"
|
|
}
|
|
out["text"] = body
|
|
return out, nil
|
|
}
|
|
|
|
func refused(caller, account string) error {
|
|
return fmt.Errorf("refused: %s is not granted the mail account %s; the operator grants it through the setting grants", caller, account)
|
|
}
|
|
|
|
// ---- mail_send, mail_send_status ---------------------------------------------------------------------------------
|
|
|
|
// askBus is the operator channel this bundle reaches: the bus's own, unless a test gave one.
|
|
func (b *Bundle) askBus() AskBus {
|
|
if b.Asks != nil {
|
|
return b.Asks
|
|
}
|
|
return sdkAskBus{}
|
|
}
|
|
|
|
// sends is the `sends` state this bundle keeps: the bus's own, unless a test gave one.
|
|
func (b *Bundle) sends() SendStore {
|
|
if b.Sends != nil {
|
|
return b.Sends
|
|
}
|
|
return keptSends{stdio.State(SendsState)}
|
|
}
|
|
|
|
// lookupAccount resolves an account by name as the settings currently hold it — read fresh at decide time, never
|
|
// the account as it stood when it was asked.
|
|
func (b *Bundle) lookupAccount(name string) (Account, bool) {
|
|
accounts, err := ReadAccounts(b.Env.Accounts)
|
|
if err != nil {
|
|
return Account{}, false
|
|
}
|
|
return accountByName(accounts, name)
|
|
}
|
|
|
|
func accountByName(accounts []Account, name string) (Account, bool) {
|
|
for _, a := range accounts {
|
|
if a.Name == name {
|
|
return a, true
|
|
}
|
|
}
|
|
return Account{}, false
|
|
}
|
|
|
|
// sendActor performs one send on the operator's Approve: it reads the account's own secret itself, so Decide and
|
|
// the `sends` state never hold a password.
|
|
func (b *Bundle) sendActor() SendActor {
|
|
dial := b.Dial
|
|
if dial == nil {
|
|
dial = DialSMTP
|
|
}
|
|
return func(a Account, to []string, subject, body string, now time.Time) error {
|
|
pw, given, err := ReadSecret(b.Env.Secrets, a)
|
|
if err != nil {
|
|
return fmt.Errorf("the account %s's password cannot be read: %w", a.Name, err)
|
|
}
|
|
if !given {
|
|
return fmt.Errorf("the account %s has no password yet; the operator gives it at the desk", a.Name)
|
|
}
|
|
return SendMail(dial, a, pw, to, subject, body, now)
|
|
}
|
|
}
|
|
|
|
func stringList(v any) []string {
|
|
list, _ := v.([]any)
|
|
out := make([]string, 0, len(list))
|
|
for _, item := range list {
|
|
if s, ok := item.(string); ok {
|
|
out = append(out, s)
|
|
}
|
|
}
|
|
return out
|
|
}
|
|
|
|
func (b *Bundle) sendTool(args map[string]any) (any, error) {
|
|
if err := only(args, "account", "to", "subject", "body"); err != nil {
|
|
return nil, err
|
|
}
|
|
account, _ := args["account"].(string)
|
|
subject, _ := args["subject"].(string)
|
|
body, _ := args["body"].(string)
|
|
to := stringList(args["to"])
|
|
if account == "" {
|
|
return nil, fmt.Errorf("%s needs account, by its name in mail_accounts", SendTool)
|
|
}
|
|
accounts, grants, err := b.settings()
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
caller := b.caller(args)
|
|
// The same grants check as mail_read (novox/hq ADR 0359 §4, ADR 0361 §2): an ungranted caller is refused, and
|
|
// nothing is asked.
|
|
if !grants.Allows(caller, account) {
|
|
return nil, grants.refuse(caller, account)
|
|
}
|
|
acc, found := accountByName(accounts, account)
|
|
if !found {
|
|
return nil, fmt.Errorf("no account %q is held; mail_accounts lists the accounts", account)
|
|
}
|
|
return AskMailSend(SendInput{Account: acc, To: to, Subject: subject, Body: body, Caller: caller, Accounts: accounts},
|
|
b.sends(), b.askBus(), b.now())
|
|
}
|
|
|
|
func (b *Bundle) sendStatusTool(args map[string]any) (any, error) {
|
|
if err := only(args, "id"); err != nil {
|
|
return nil, err
|
|
}
|
|
id, _ := args["id"].(string)
|
|
if id == "" {
|
|
return nil, fmt.Errorf("%s needs id, the ask %s gave", SendStatusTool, SendTool)
|
|
}
|
|
return ReadSendStatus(b.sends(), b.askBus(), b.lookupAccount, b.sendActor(), id, b.now())
|
|
}
|
|
|
|
// ---- arguments ----------------------------------------------------------------------------------------------------
|
|
|
|
// only refuses an argument the tool does not take: never ignored, and none can say who calls.
|
|
func only(args map[string]any, takes ...string) error {
|
|
for k := range args {
|
|
if !contains(takes, k) {
|
|
return fmt.Errorf("the argument %q is not taken", k)
|
|
}
|
|
}
|
|
return nil
|
|
}
|
|
|
|
func number(args map[string]any, key string, otherwise int) (int, error) {
|
|
v, ok := args[key]
|
|
if !ok || v == nil {
|
|
return otherwise, nil
|
|
}
|
|
f, ok := v.(float64)
|
|
if !ok || f != float64(int(f)) {
|
|
return 0, errors.New(key + " is a whole number")
|
|
}
|
|
return int(f), nil
|
|
}
|
|
|
|
func text(d string) map[string]any { return map[string]any{"type": "string", "description": d} }
|
|
func integer(d string) map[string]any { return map[string]any{"type": "integer", "description": d} }
|
|
|
|
func schema(required []string, props map[string]any) map[string]any {
|
|
s := map[string]any{"type": "object", "properties": props, "additionalProperties": false}
|
|
if len(required) > 0 {
|
|
s["required"] = required
|
|
}
|
|
return s
|
|
}
|