mesh-mail-reader: its callers list goes; every verb answers every caller

Every account may call every verb; what protects the mail is what the verbs
answer (ADR 0459 §2), not who may call them.

Builds: design 47 H §764 (every callers list, §752); H-A-122

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
This commit is contained in:
2026-11-20 06:10:56 +01:00
parent c775aab29a
commit 8c8b4367f1
12 changed files with 31 additions and 325 deletions
@@ -1,84 +0,0 @@
package main
// Callers is the trusted setting `callers` (lead-m2@g14's decision at this milestone's prepare step, said to
// the operator; novox/hq ADR 0459 §2: "each answers only a caller the operator grants it"): who may call one
// of mail-reading's six verbs. An entry is a bare module name (granted wherever it runs, on any machine),
// exactly <machine>.<module>, or exactly person.<name> — the same shapes mesh-mail's own trusted setting
// `grants` matches (modules/mesh-mail/cmd/mesh-mail/config.go, Grants.Allows), copied here in miniature (one
// flat list, not one per account) so mesh-mail-reader never imports mesh-mail. Nobody beyond the list is
// granted, a wildcard in the list is no entry, and an unproven caller never matches. The setting's default is
// ["mesh-mail-web"].
import (
"encoding/json"
"errors"
"fmt"
"os"
"strings"
)
// Unproven is the caller the runtime proved nobody to be (stdio.Unproven; copied so this file reads alone).
const Unproven = "unproven"
// Callers is the setting's shape once read: a flat list of entries.
type Callers []string
// callersFile is the shape of the setting as the mesh writes it.
type callersFile struct {
Callers Callers `json:"callers"`
}
// ReadCallers reads the callers setting. A setting that cannot be read allows nobody, and says why: a caller
// refused for a reason it can read is better than one let through because the setting was unreadable.
func ReadCallers(path string) (Callers, error) {
if path == "" {
return nil, errors.New("the module was started without its callers setting (MESH_MAIL_READER_CALLERS)")
}
raw, err := os.ReadFile(path)
if err != nil {
return nil, fmt.Errorf("the callers setting cannot be read: %w", err)
}
return ParseCallers(raw)
}
// ParseCallers reads the callers setting's content.
func ParseCallers(raw []byte) (Callers, error) {
var f callersFile
dec := json.NewDecoder(strings.NewReader(string(raw)))
dec.DisallowUnknownFields()
if err := dec.Decode(&f); err != nil {
return nil, fmt.Errorf("the callers setting is not the module's: %v", err)
}
return f.Callers, nil
}
// Allows says whether the caller may call a mail-reading verb: a bare module name (on any machine, as long as
// the caller is not person.<name>), exactly <machine>.<module>, or exactly person.<name>. Nobody is granted by
// default, an unproven caller never, and a wildcard entry is no entry (mesh-mail's own Grants.Allows mirrored).
func (c Callers) Allows(caller string) bool {
if caller == "" || caller == Unproven {
return false
}
for _, entry := range c {
if entry == "" || strings.ContainsAny(entry, "*>") {
continue
}
if entry == caller {
return true
}
if !strings.Contains(entry, ".") {
if _, module, ok := strings.Cut(caller, "."); ok && module == entry && !strings.HasPrefix(caller, "person.") {
return true
}
}
}
return false
}
// refuseCaller says why the caller is refused a mail-reading verb: the setting unread, or simply not named in it.
func refuseCaller(readErr error, caller string) error {
if readErr != nil {
return fmt.Errorf("refused: the setting callers cannot be read, so it allows nobody: %w", readErr)
}
return fmt.Errorf("refused: %s is not named in the setting callers; the operator grants it there", caller)
}
@@ -1,52 +0,0 @@
package main
// 1426/AC4: the trusted setting callers, per shape, and an unproven caller.
import "testing"
func TestCallersAllowsEachShape(t *testing.T) {
c := Callers{"mesh-mail-web", "novox.mesh-knowledge", "person.jochen"}
cases := []struct {
caller string
want bool
}{
{"mesh-mail-web", true}, // a bare module name
{"shanks.mesh-mail-web", true}, // ... on any machine
{"novox.mesh-knowledge", true}, // exactly <machine>.<module>
{"shanks.mesh-knowledge", false}, // ... but not on another machine
{"person.jochen", true}, // exactly person.<name>
{"person.someoneelse", false}, // ... but not another person
{"mesh-mail-notifier", false}, // not named at all
{"", false},
{Unproven, false}, // 1426/AC4: unproven never
}
for _, c2 := range cases {
if got := c.Allows(c2.caller); got != c2.want {
t.Errorf("Allows(%q) = %v, want %v", c2.caller, got, c2.want)
}
}
}
// 1426/AC4: a wildcard entry is no entry (mirrors mesh-mail's own Grants.Allows).
func TestCallersWildcardEntryIsNoEntry(t *testing.T) {
c := Callers{"*", "mesh-mail.>"}
if c.Allows("anything") {
t.Fatal("a wildcard entry granted a caller")
}
}
func TestParseCallersDefault(t *testing.T) {
c, err := ParseCallers([]byte(`{"callers": ["mesh-mail-web"]}`))
if err != nil {
t.Fatal(err)
}
if len(c) != 1 || c[0] != "mesh-mail-web" {
t.Fatalf("callers = %v", c)
}
}
func TestReadCallersEmptyPath(t *testing.T) {
if _, err := ReadCallers(""); err == nil {
t.Fatal("no error reading callers with no path")
}
}
@@ -9,9 +9,7 @@ import (
func testBundle(store Store, caller string) *Bundle {
return &Bundle{
Caller: func(map[string]any) string { return caller },
callersOverride: func() (Callers, error) { return Callers{"mesh-mail-web"}, nil },
Store: func(context.Context) (Store, error) { return store, nil },
Store: func(context.Context) (Store, error) { return store, nil },
}
}
@@ -115,9 +115,7 @@ func TestEntriesToolAnswersFilteredAndSorted(t *testing.T) {
store.AddEntry(ctx, Entry{Account: "bob", Subject: "b", Mark: MarkMatters, DueDate: time.Date(2026, 11, 1, 0, 0, 0, 0, time.UTC), Date: time.Date(2026, 10, 2, 0, 0, 0, 0, time.UTC)})
b := &Bundle{
Caller: func(map[string]any) string { return "mesh-mail-web" },
callersOverride: func() (Callers, error) { return Callers{"mesh-mail-web"}, nil },
Store: func(context.Context) (Store, error) { return store, nil },
Store: func(context.Context) (Store, error) { return store, nil },
}
out, err := b.entriesTool(map[string]any{"group": "newsletters"})
if err != nil {
@@ -150,9 +148,7 @@ func TestGroupsToolAnswersLargestFirst(t *testing.T) {
store.AddEntry(ctx, Entry{Group: big.ID})
b := &Bundle{
Caller: func(map[string]any) string { return "mesh-mail-web" },
callersOverride: func() (Callers, error) { return Callers{"mesh-mail-web"}, nil },
Store: func(context.Context) (Store, error) { return store, nil },
Store: func(context.Context) (Store, error) { return store, nil },
}
out, err := b.groupsTool(map[string]any{})
if err != nil {
@@ -172,9 +168,7 @@ func TestStatusToolAnswersHealthAndWeeklyMeasure(t *testing.T) {
store.SetReaderHealth(ctx, ReaderHealth{Healthy: false, Cause: OutcomeRefused, Why: "holds no licence", Since: since})
b := &Bundle{
Caller: func(map[string]any) string { return "mesh-mail-web" },
callersOverride: func() (Callers, error) { return Callers{"mesh-mail-web"}, nil },
Store: func(context.Context) (Store, error) { return store, nil },
Store: func(context.Context) (Store, error) { return store, nil },
}
out, err := b.statusTool(map[string]any{})
if err != nil {
@@ -82,9 +82,7 @@ func TestHealthToolReadsTheKeptState(t *testing.T) {
// A fresh Bundle, as a restarted process would build one, reading the same store.
b := &Bundle{
Caller: func(map[string]any) string { return "mesh-mail-web" },
callersOverride: func() (Callers, error) { return Callers{"mesh-mail-web"}, nil },
Store: func(context.Context) (Store, error) { return store, nil },
Store: func(context.Context) (Store, error) { return store, nil },
}
got, err := b.healthTool(map[string]any{})
if err != nil {
@@ -30,10 +30,6 @@ const Module = "mesh-mail-reader"
func logf(format string, a ...any) { fmt.Fprintf(os.Stderr, format+"\n", a...) }
func envFromOS() Env {
return Env{Callers: os.Getenv("MESH_MAIL_READER_CALLERS")}
}
// cachedStore opens the index once, lazily, and hands every later caller that SAME store (review round 1
// finding 2, issue 1517/1518): the Bundle's own tool calls (one per mesh/ask, tools.go), hearLoop's handler
// (one per event heard) and batchLoop. Before this, each of those called storeFor itself, which opened a
@@ -71,7 +67,7 @@ func main() {
os.Exit(prepare())
}
store := newCachedStore(func(ctx context.Context) (Store, error) { return PgStoreFromEnv(ctx) })
b := &Bundle{Env: envFromOS(), Store: store.get}
b := &Bundle{Store: store.get}
go hearLoop(store.get, stdio.Subscribe, time.Sleep)
go batchLoop(store.get)
if err := stdio.ServeOn("", b.Tools(), os.Stdin, os.Stdout); err != nil {
@@ -518,18 +518,12 @@ func startReader(t *testing.T) *startedReader {
if err := os.WriteFile(dbPath, []byte(dbURL), 0o600); err != nil {
t.Fatal(err)
}
callersPath := filepath.Join(dir, "callers.json")
callersJSON, _ := json.Marshal(map[string]any{"callers": []string{"mesh-mail-web"}})
if err := os.WriteFile(callersPath, callersJSON, 0o600); err != nil {
t.Fatal(err)
}
stand := &standIns{}
env := append(os.Environ(),
"MESH_NODE="+testNode,
"MESH_SERVED_MODULE=mesh-mail-reader",
"DATABASE_URL_FILE="+dbPath,
"MESH_MAIL_READER_CALLERS="+callersPath,
)
player := startReaderPlayer(t, binary, env, stand, nc, nil)
return &startedReader{player: player, stand: stand, nc: nc, dbURL: dbURL}
@@ -1,10 +1,9 @@
package main
// The module's tools (novox/hq ADR 0459 §2, issue 1426): the six mail-reading seat verbs — entries, groups,
// correct, lessons, undo, status — and the module's own health tool, mail_reader_health (1519). Who calls is
// the runtime's word (stdio.CallerOf), never an argument; a mail-reading verb answers only a caller the
// trusted setting `callers` names (callers.go), and refuses any other, naming why. mail_reader_health is
// asked by the node-engine itself and carries no caller check.
// correct, lessons, undo, status — and the module's own health tool, mail_reader_health (1519). Every verb
// answers every caller: the module keeps no callers list (design 47 H, H-A-122; every account may call every
// verb); what protects the mail is what the verbs answer, never a body (ADR 0459 §2).
//
// The six verbs' own behaviour — reading and writing mail entries, mail groups and reading lessons — is
// 1521 (entries, groups, status) and 1428 (correct, lessons, undo): all six now answer for real.
@@ -31,46 +30,9 @@ const (
StatusTool = "mail-reading.status"
)
// Bundle is what the tools reach: the trusted setting `callers`, the runtime's own caller, and the index
// (store.go), which mail_reader_health reads (1519). Caller is nil outside a test (CallerOf is read from the
// runtime).
// Bundle is what the tools reach: the index (store.go), which mail_reader_health reads too (1519).
type Bundle struct {
Env Env
Caller func(args map[string]any) string
Store func(ctx context.Context) (Store, error)
// callersOverride, when set, is used instead of reading Env.Callers — the tests' own seam.
callersOverride func() (Callers, error)
}
// Env is where the bundle reads its settings from.
type Env struct {
Callers string // the path MESH_MAIL_READER_CALLERS names.
}
func (b *Bundle) caller(args map[string]any) string {
if b.Caller != nil {
return b.Caller(args)
}
return stdio.CallerOf(args)
}
func (b *Bundle) callers() (Callers, error) {
if b.callersOverride != nil {
return b.callersOverride()
}
return ReadCallers(b.Env.Callers)
}
// checkCaller refuses args' caller unless the trusted setting `callers` names it (1426/AC4). It is the first
// thing every mail-reading verb does: a caller learns it is refused before it learns anything about the verb.
func (b *Bundle) checkCaller(args map[string]any) (string, error) {
caller := b.caller(args)
callers, err := b.callers()
if err != nil || !callers.Allows(caller) {
return caller, refuseCaller(err, caller)
}
return caller, nil
Store func(ctx context.Context) (Store, error)
}
// schema, text, integer and boolean mirror mesh-mail's own tools.go helpers (modules/mesh-mail/cmd/mesh-mail,
@@ -125,7 +87,7 @@ func (b *Bundle) Tools() []stdio.Tool {
Description: "Every mail entry (novox/hq ADR 0459 §4): the mail's own headers, its mail group, a " +
"one-line summary, its mark and why, its due date — never a mail body. Newest first, except a " +
"mail that matters comes first, nearest due date first among those (none last). Filtered by mail " +
"group (its label) or by mark when asked. Answered only to a caller the setting callers names. " +
"group (its label) or by mark when asked. " +
"Read-only.",
Input: schema(nil, map[string]any{
"limit": integer("how many to answer; a default bounds it when left out"),
@@ -135,7 +97,7 @@ func (b *Bundle) Tools() []stdio.Tool {
Run: b.entriesTool},
{Name: GroupsTool,
Description: "Every mail group a batch has made (novox/hq ADR 0459 §4, §5), with how many mails it " +
"holds, largest first. Answered only to a caller the setting callers names. Read-only.",
"holds, largest first. Read-only.",
Input: schema(nil, map[string]any{
"limit": integer("how many to answer; a default bounds it when left out"),
}),
@@ -144,7 +106,7 @@ func (b *Bundle) Tools() []stdio.Tool {
Description: "Correct one mail entry's mark, mail group, why or due date (novox/hq ADR 0459 §8): " +
"kept at once as a reading lesson (the mail's own headers, the change made, when), no operator " +
"Approve needed, and outranking that mail's own words in any later batch. Refused for an unknown " +
"mail id or mark. Answered only to a caller the setting callers names.",
"mail id or mark.",
Input: schema([]string{"id"}, map[string]any{
"id": integer("the mail entry's id, as entries answered it"),
"mark": text("the corrected mark: matters, scam warning or neither"),
@@ -156,8 +118,7 @@ func (b *Bundle) Tools() []stdio.Tool {
{Name: LessonsTool,
Description: "The reading lessons kept (novox/hq ADR 0459 §9): newest first, at most 40 (fewer when " +
"asked); undone ones left out unless include-undone asks for them, each then marked undone. A " +
"lesson outranks a mail it would otherwise contradict. Answered only to a caller the setting " +
"callers names. Read-only.",
"lesson outranks a mail it would otherwise contradict. Read-only.",
Input: schema(nil, map[string]any{
"limit": integer("how many to answer, at most 40; a default bounds it when left out"),
"include-undone": boolean("also answer undone lessons, each marked undone; left out by default"),
@@ -165,7 +126,7 @@ func (b *Bundle) Tools() []stdio.Tool {
Run: b.lessonsTool},
{Name: UndoTool,
Description: "Undo one reading lesson (novox/hq ADR 0459 §9, issue 1523): it no longer outranks a " +
"mail. Answered only to a caller the setting callers names.",
"mail.",
Input: schema([]string{"id"}, map[string]any{
"id": integer("the reading lesson's id, as lessons answered it"),
}),
@@ -173,7 +134,7 @@ func (b *Bundle) Tools() []stdio.Tool {
{Name: StatusTool,
Description: "How mail reading stands for the page (novox/hq ADR 0459 §10): healthy or not, the cause " +
"and since when, and reading lessons per 100 read mails for each of the last 8 weeks (a week with " +
"no mail read says so). Answered only to a caller the setting callers names. Read-only.",
"no mail read says so). Read-only.",
Input: schema(nil, map[string]any{}),
Run: b.statusTool},
{Name: HealthTool,
@@ -200,9 +161,6 @@ func entryOut(e Entry, labels map[int64]string) map[string]any {
}
func (b *Bundle) entriesTool(args map[string]any) (any, error) {
if _, err := b.checkCaller(args); err != nil {
return nil, err
}
if err := only(args, "limit", "group", "mark"); err != nil {
return nil, err
}
@@ -254,9 +212,6 @@ func (b *Bundle) entriesTool(args map[string]any) (any, error) {
}
func (b *Bundle) groupsTool(args map[string]any) (any, error) {
if _, err := b.checkCaller(args); err != nil {
return nil, err
}
if err := only(args, "limit"); err != nil {
return nil, err
}
@@ -294,9 +249,6 @@ func validMark(s string) (Mark, error) {
}
func (b *Bundle) correctTool(args map[string]any) (any, error) {
if _, err := b.checkCaller(args); err != nil {
return nil, err
}
if err := only(args, "id", "mark", "group", "why", "due-date"); err != nil {
return nil, err
}
@@ -397,9 +349,6 @@ func groupLabels(ctx context.Context, store Store) (map[int64]string, error) {
}
func (b *Bundle) lessonsTool(args map[string]any) (any, error) {
if _, err := b.checkCaller(args); err != nil {
return nil, err
}
if err := only(args, "limit", "include-undone"); err != nil {
return nil, err
}
@@ -443,9 +392,6 @@ func (b *Bundle) lessonsTool(args map[string]any) (any, error) {
}
func (b *Bundle) undoTool(args map[string]any) (any, error) {
if _, err := b.checkCaller(args); err != nil {
return nil, err
}
if err := only(args, "id"); err != nil {
return nil, err
}
@@ -473,9 +419,6 @@ func (b *Bundle) undoTool(args map[string]any) (any, error) {
}
func (b *Bundle) statusTool(args map[string]any) (any, error) {
if _, err := b.checkCaller(args); err != nil {
return nil, err
}
if err := only(args); err != nil {
return nil, err
}
@@ -2,7 +2,6 @@ package main
import (
"context"
"strings"
"testing"
)
@@ -34,76 +33,21 @@ func TestToolsListsTheSixVerbsAndHealth(t *testing.T) {
}
}
// 1426/AC4, 1428/AC5: a mail-reading verb answers a caller the setting callers names, and refuses any other,
// naming why — before anything else about the verb (business errors such as an unknown id are not caller
// refusals, and are exercised by correct_test.go and 1521's own tests, not here).
func TestAMailReadingVerbChecksItsCaller(t *testing.T) {
granted := func(map[string]any) string { return "mesh-mail-web" }
refused := func(map[string]any) string { return "person.someoneelse" }
unproven := func(map[string]any) string { return Unproven }
storeOf := func(context.Context) (Store, error) { return newMemStore(), nil }
// Design 47 H, H-A-122: a mail-reading verb answers every caller, even one the runtime proved nobody to be (the
// caller of arguments no call was handed): the module keeps no callers list.
func TestAMailReadingVerbAnswersEveryCaller(t *testing.T) {
b := &Bundle{Store: func(context.Context) (Store, error) { return newMemStore(), nil }}
for _, tool := range []struct {
name string
run func(*Bundle) (any, error)
run func() (any, error)
}{
{EntriesTool, func(b *Bundle) (any, error) { return b.entriesTool(map[string]any{}) }},
{GroupsTool, func(b *Bundle) (any, error) { return b.groupsTool(map[string]any{}) }},
{CorrectTool, func(b *Bundle) (any, error) {
return b.correctTool(map[string]any{"id": float64(1), "mark": "matters"})
}},
{LessonsTool, func(b *Bundle) (any, error) { return b.lessonsTool(map[string]any{}) }},
{UndoTool, func(b *Bundle) (any, error) { return b.undoTool(map[string]any{"id": float64(1)}) }},
{StatusTool, func(b *Bundle) (any, error) { return b.statusTool(map[string]any{}) }},
{EntriesTool, func() (any, error) { return b.entriesTool(map[string]any{}) }},
{GroupsTool, func() (any, error) { return b.groupsTool(map[string]any{}) }},
{LessonsTool, func() (any, error) { return b.lessonsTool(map[string]any{}) }},
{StatusTool, func() (any, error) { return b.statusTool(map[string]any{}) }},
} {
callers := func() (Callers, error) { return Callers{"mesh-mail-web"}, nil }
b := &Bundle{Caller: granted, callersOverride: callers, Store: storeOf}
_, err := tool.run(b)
if err != nil && strings.Contains(err.Error(), "is not named in the setting callers") {
t.Errorf("%s granted: %v, want it to pass the caller check (any other error is its own business, not a caller refusal)", tool.name, err)
}
b = &Bundle{Caller: refused, callersOverride: callers, Store: storeOf}
_, err = tool.run(b)
if err == nil || !strings.Contains(err.Error(), "refused") || !strings.Contains(err.Error(), "person.someoneelse") {
t.Errorf("%s refused caller: %v, want a refusal naming person.someoneelse", tool.name, err)
}
b = &Bundle{Caller: unproven, callersOverride: callers, Store: storeOf}
_, err = tool.run(b)
if err == nil || !strings.Contains(err.Error(), "refused") {
t.Errorf("%s unproven caller: %v, want a refusal", tool.name, err)
if _, err := tool.run(); err != nil {
t.Errorf("%s: %v, want an answer to any caller", tool.name, err)
}
}
}
// 1426/AC4: a setting that cannot be read allows nobody, and says why — before the store is ever reached.
func TestAMailReadingVerbRefusesWhenCallersCannotBeRead(t *testing.T) {
b := &Bundle{
Caller: func(map[string]any) string { return "mesh-mail-web" },
callersOverride: func() (Callers, error) { return nil, errFake },
}
_, err := b.entriesTool(map[string]any{})
if err == nil || !strings.Contains(err.Error(), "cannot be read") {
t.Fatalf("entriesTool with an unreadable setting: %v", err)
}
}
// mail_reader_health carries no caller check (1426: "mail_reader_health is asked by the node-engine itself").
func TestHealthToolHasNoCallerCheck(t *testing.T) {
b := &Bundle{
callersOverride: func() (Callers, error) { return nil, errFake },
Store: func(context.Context) (Store, error) { return newMemStore(), nil },
}
_, err := b.healthTool(map[string]any{})
if err != nil {
t.Fatalf("mail_reader_health: %v, want it to skip the caller check entirely and answer", err)
}
}
type fakeErr struct{}
func (fakeErr) Error() string { return "the setting cannot be read (fake)" }
var errFake = fakeErr{}