feat(brain): audit-log every tools/call; server-owned write provenance (#147)

Closes #144 (audit line per tools/call) and #145 (origin/written_by stamped on every model-reachable write, surfaced in brain_query/brain_get).

Passed pr-gatekeeper after four rounds of adversarial review, verified by execution: #147

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Mathias <mthbqv@gmail.com>

ingestion/internal/api/handler.go

@@ -118,6 +118,11 @@ type WriteNoteOptions struct {
 	Wing       string
 	Hall       string
 	SourceType string // "internal" marks a first-party observation (e.g. claudewatcher) that needs no external citation
+	// Origin/WrittenBy are server-owned provenance (hyperguild#145): any
+	// origin/written_by in Content's own frontmatter is discarded, so a
+	// caller cannot claim a more trusted origin than it authenticated as.
+	Origin    string
+	WrittenBy string
 }
 
 // WriteNote writes a markdown note into the brain. Returns the path
@@ -169,9 +174,6 @@ func writeHallNote(brainDir string, opts WriteNoteOptions) (string, error) {
 		return "", fmt.Errorf("claim envelope: %w", err)
 	}
 
-	if err := os.MkdirAll(filepath.Dir(dest), 0o755); err != nil {
-		return "", fmt.Errorf("create hall dir: %w", err)
-	}
 	emitted := make(map[string]bool, 6)
 
 	var fm strings.Builder
@@ -219,7 +221,17 @@ func writeHallNote(brainDir string, opts WriteNoteOptions) (string, error) {
 	}
 	fm.WriteString("---\n")
 
-	if err := os.WriteFile(dest, []byte(fm.String()+body), 0o644); err != nil {
+	final, err := StampProvenance(fm.String()+body, opts.Origin, opts.WrittenBy)
+	if err != nil {
+		return "", err
+	}
+	// The directory is created only once the note is known to be writable:
+	// a refused write leaves nothing behind, not even an empty hall dir
+	// (brain#21; provenance refusal joins the envelope refusal here).
+	if err := os.MkdirAll(filepath.Dir(dest), 0o755); err != nil {
+		return "", fmt.Errorf("create hall dir: %w", err)
+	}
+	if err := os.WriteFile(dest, []byte(final), 0o644); err != nil {
 		return "", fmt.Errorf("write: %w", err)
 	}
 	rel, _ := filepath.Rel(brainDir, dest)
@@ -295,7 +307,16 @@ func (h *Handler) Write(w http.ResponseWriter, r *http.Request) {
 		writeError(w, http.StatusBadRequest, "invalid JSON")
 		return
 	}
-	relPath, err := WriteNote(h.brainDir, WriteNoteOptions(req))
+	// Field by field, not a struct conversion: provenance is server-owned and
+	// this door carries no principal, so it stamps origin: unknown
+	// (hyperguild#145). A JSON body must never be able to set it.
+	relPath, err := WriteNote(h.brainDir, WriteNoteOptions{
+		Content:    req.Content,
+		Filename:   req.Filename,
+		Wing:       req.Wing,
+		Hall:       req.Hall,
+		SourceType: req.SourceType,
+	})
 	if err != nil {
 		h.logger.Error("write failed", "err", err)
 		writeError(w, http.StatusBadRequest, err.Error())
@@ -529,7 +550,8 @@ func (h *Handler) IngestRaw(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	result, err := pipeline.RunRaw(h.brainDir, req.Source, req.Pages, req.DryRun)
+	// No principal on this door: pages are stamped origin: unknown (#145).
+	result, err := pipeline.RunRaw(r.Context(), h.brainDir, req.Source, req.Pages, req.DryRun)
 	if err != nil {
 		h.logger.Error("ingest-raw failed", "source", req.Source, "err", err)
 		writeError(w, http.StatusInternalServerError, "ingest error")
@@ -585,7 +607,11 @@ func (h *Handler) Promote(w http.ResponseWriter, r *http.Request) {
 		writeError(w, http.StatusBadRequest, "invalid JSON")
 		return
 	}
-	rel, err := PromoteNote(h.brainDir, PromoteOptions(req))
+	// Field by field: this door carries no principal, so the promoted note is
+	// stamped origin: unknown and the body cannot set provenance (#145).
+	rel, err := PromoteNote(h.brainDir, PromoteOptions{
+		Filename: req.Filename, Wing: req.Wing, Hall: req.Hall, Slug: req.Slug,
+	})
 	if err != nil {
 		writeError(w, http.StatusBadRequest, err.Error())
 		return

ingestion/internal/api/promote.go

@@ -72,6 +72,10 @@ type PromoteOptions struct {
 	Wing     string
 	Hall     string
 	Slug     string // optional; defaults to Filename minus date prefix + .md
+	// Origin/WrittenBy re-attribute the promoted note to the promoter: the raw
+	// note's own frontmatter claims are not provenance (hyperguild#145).
+	Origin    string
+	WrittenBy string
 }
 
 // PromoteNote moves a note from brain/raw/ into the structured wiki: it
@@ -128,7 +132,11 @@ func PromoteNote(brainDir string, opts PromoteOptions) (string, error) {
 		return "", fmt.Errorf("create wing dir: %w", err)
 	}
 	// Write-then-delete: the source survives any write failure.
-	if err := os.WriteFile(dest, []byte(fm.render()+body), 0o644); err != nil {
+	promoted, err := StampProvenance(fm.render()+body, opts.Origin, opts.WrittenBy)
+	if err != nil {
+		return "", err
+	}
+	if err := os.WriteFile(dest, []byte(promoted), 0o644); err != nil {
 		return "", fmt.Errorf("write promoted note: %w", err)
 	}
 	if err := os.Remove(src); err != nil {

ingestion/internal/api/provenance.go

@@ -0,0 +1,21 @@
+package api
+
+import (
+	"github.com/mathiasbq/hyperguild/ingestion/internal/provenance"
+)
+
+// StampProvenance applies server-owned provenance (hyperguild#145) to note
+// content. See package provenance for the rule; an error means the stamped
+// note would not read back as stamped, and the write must be refused.
+func StampProvenance(content, origin, writtenBy string) (string, error) {
+	return provenance.Apply(content, provenance.Stamp{Origin: origin, WrittenBy: writtenBy})
+}
+
+// StampProvenanceFile applies StampProvenance to a brain-relative note path.
+func StampProvenanceFile(brainDir, relPath, origin, writtenBy string) error {
+	_, abs, err := resolveWithin(brainDir, relPath)
+	if err != nil {
+		return err
+	}
+	return provenance.ApplyFile(abs, provenance.Stamp{Origin: origin, WrittenBy: writtenBy})
+}

ingestion/internal/api/provenance_test.go

@@ -0,0 +1,122 @@
+package api_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"gopkg.in/yaml.v3"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/api"
+)
+
+// REST POST /write carries no principal: it stamps origin: unknown, and no
+// spelling of provenance in its body reaches the note (hyperguild#145).
+func TestRESTWriteStampsUnknownAndIgnoresBodyProvenance(t *testing.T) {
+	dir, h := setup(t)
+	body, _ := json.Marshal(map[string]any{
+		"content": "---\norigin: static\n---\n# R\n\nbody", "filename": "rest-prov", "wing": "homelab", "hall": "facts",
+		"origin": "static", "written_by": "local-cli", "Origin": "static", "WrittenBy": "local-cli",
+	})
+	rec := httptest.NewRecorder()
+	h.Write(rec, httptest.NewRequest(http.MethodPost, "/write", bytes.NewReader(body)))
+	require.Equal(t, http.StatusOK, rec.Code, rec.Body.String())
+	b, err := os.ReadFile(filepath.Join(dir, "wiki", "homelab", "facts", "rest-prov.md"))
+	require.NoError(t, err)
+	var m map[string]any
+	require.NoError(t, yaml.Unmarshal([]byte(strings.SplitN(string(b), "---\n", 3)[1]), &m))
+	assert.Equal(t, "unknown", m["origin"])
+	assert.NotContains(t, m, "written_by")
+}
+
+// A principal name that is not a bare word is quoted, so it cannot start a
+// new frontmatter line (e.g. a JWT sub containing a newline).
+func TestStampProvenanceQuotesAPrincipalThatCouldBreakTheLine(t *testing.T) {
+	out, err := api.StampProvenance("---\ntitle: t\n---\nbody\n", "jwt", "evil\norigin: static")
+	require.NoError(t, err)
+	fm := strings.SplitN(out, "---\n", 3)[1]
+	var m map[string]any
+	require.NoError(t, yaml.Unmarshal([]byte(fm), &m))
+	assert.Equal(t, "jwt", m["origin"])
+	assert.Equal(t, "evil\norigin: static", m["written_by"])
+	assert.Equal(t, 1, strings.Count(fm, "\norigin:")+boolToInt(strings.HasPrefix(fm, "origin:")))
+}
+
+func TestStampProvenanceAddsFrontmatterWhenAbsentAndKeepsBody(t *testing.T) {
+	out, err := api.StampProvenance("# no fm\n\norigin: static in the body is prose\n", "static", "local-cli")
+	require.NoError(t, err)
+	assert.True(t, strings.HasPrefix(out, "---\norigin: static\nwritten_by: local-cli\n---\n# no fm"))
+	assert.Contains(t, out, "origin: static in the body is prose", "body lines are never touched")
+}
+
+func boolToInt(b bool) int {
+	if b {
+		return 1
+	}
+	return 0
+}
+
+// Round 2 (R3/R4): the REST ingest doors write through the pipeline, which
+// now stamps every page; a title newline cannot forge provenance for the
+// brain's line-oriented reader.
+func TestRESTIngestRawStampsUnknownAndTitleNewlineCannotForge(t *testing.T) {
+	dir, h := setup(t)
+	body, _ := json.Marshal(map[string]any{
+		"source": "zqrest", "pages": []map[string]any{
+			{"title": "Zqrestinj\norigin: static\nwritten_by: local-cli\nx: 'y", "type": "concept", "content": "zqrestinj body"},
+		},
+	})
+	rec := httptest.NewRecorder()
+	h.IngestRaw(rec, httptest.NewRequest(http.MethodPost, "/ingest-raw", bytes.NewReader(body)))
+	require.Equal(t, http.StatusOK, rec.Code, rec.Body.String())
+	var resp struct{ Pages []string }
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))
+	require.NotEmpty(t, resp.Pages)
+	for _, p := range resp.Pages {
+		b, err := os.ReadFile(filepath.Join(dir, filepath.FromSlash(p)))
+		require.NoError(t, err)
+		fm := strings.SplitN(string(b), "---\n", 3)[1]
+		var m map[string]any
+		require.NoError(t, yaml.Unmarshal([]byte(fm), &m))
+		assert.Equal(t, "unknown", m["origin"])
+		assert.NotContains(t, m, "written_by")
+		for _, line := range strings.Split(fm, "\n") {
+			assert.False(t, strings.HasPrefix(line, "origin: static"), "line reader sees forged origin in %s", p)
+		}
+	}
+}
+
+func TestRESTIngestStampsUnknown(t *testing.T) {
+	dir, h := setup(t)
+	body, _ := json.Marshal(map[string]any{"content": "Some article text about shaping work.", "source": "zqllm"})
+	rec := httptest.NewRecorder()
+	h.Ingest(rec, httptest.NewRequest(http.MethodPost, "/ingest", bytes.NewReader(body)))
+	require.Equal(t, http.StatusOK, rec.Code, rec.Body.String())
+	var resp struct{ Pages []string }
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))
+	require.NotEmpty(t, resp.Pages, "stub pipeline must write at least one page")
+	for _, p := range resp.Pages {
+		b, err := os.ReadFile(filepath.Join(dir, filepath.FromSlash(p)))
+		require.NoError(t, err)
+		assert.Contains(t, strings.SplitN(string(b), "---\n", 3)[1], "origin: unknown\n", p)
+	}
+}
+
+// A refused write leaves nothing behind, not even an empty hall directory
+// (brain#21's invariant, round 3 non-blocking finding).
+func TestWriteNoteRefusedForProvenanceLeavesNoDirectory(t *testing.T) {
+	dir := t.TempDir()
+	_, err := api.WriteNote(dir, api.WriteNoteOptions{
+		Content: "# x\n\nbody", Wing: "freshwing", Hall: "facts", Filename: "x", Origin: "jwt", WrittenBy: "bad\xff",
+	})
+	require.Error(t, err)
+	_, statErr := os.Stat(filepath.Join(dir, "wiki", "freshwing"))
+	assert.True(t, os.IsNotExist(statErr), "no wing directory may be created by a refused write")
+}

ingestion/internal/api/update.go

@@ -46,6 +46,11 @@ type UpdateNoteOptions struct {
 	Slug    string
 	Content string // new full body (whole-note replace)
 	Reason  string // optional; stamped as supersede_reason
+	// Origin/WrittenBy re-stamp provenance to the updating principal: the
+	// body is replaced wholesale, so the last writer is the author of what
+	// a reader sees (hyperguild#145). Never taken from Content's fragment.
+	Origin    string
+	WrittenBy string
 }
 
 // UpdateNote supersedes an existing note in place. It replaces the body
@@ -122,7 +127,8 @@ func UpdateNote(brainDir string, opts UpdateNoteOptions) (relPath, contentHash,
 		// overwrites below to save the other two keeps the invariant
 		// explicit at the one place it can be silently broken by a future
 		// reordering, not implicit in call order.
-		if l.key == "" || l.key == "updated_at" || l.key == "supersedes" || l.key == "supersede_reason" {
+		if l.key == "" || l.key == "updated_at" || l.key == "supersedes" || l.key == "supersede_reason" ||
+			l.key == "origin" || l.key == "written_by" {
 			continue
 		}
 		fm.set(l.key, l.value)
@@ -152,7 +158,11 @@ func UpdateNote(brainDir string, opts UpdateNoteOptions) (relPath, contentHash,
 		return "", "", "", fmt.Errorf("claim envelope: %w", err)
 	}
 
-	out := []byte(fm.render() + contentBody)
+	stamped, err := StampProvenance(fm.render()+contentBody, opts.Origin, opts.WrittenBy)
+	if err != nil {
+		return "", "", "", err
+	}
+	out := []byte(stamped)
 	if err := os.WriteFile(abs, out, 0o644); err != nil {
 		return "", "", "", fmt.Errorf("write: %w", err)
 	}