Feature 57 (config and provisioning): modules declare config and provisions, their files rendered from templates; synced with main (issues of feature 57, 874)

modules/gitea/cmd/forge/account_test.go

@@ -0,0 +1,120 @@
+package main
+
+// The commit and the reads act as the tools' own account (novox/hq ADR 0365 §2, issue 469): the token the module
+// keeps for `mesh-tools`, never the admin login. That account is no repository's administrator, so the forge
+// refuses it the protection rules (403, as gitea's reqAdmin does); the commit then judges an existing branch by the
+// protection the forge says it applies, and leaves a branch not made yet to the forge's own judgement.
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"gitea/internal/forgehttp"
+)
+
+const toolsToken = "tools-token-never-shown"
+
+// asTools serves the fake forge to a bundle holding the tools' token: only that token is taken, the rules are
+// refused as to a non-administrator, and the branches named protected say so as the forge does.
+func asTools(t *testing.T, f *fakeForge, protected map[string]string, scopes string) (*Forge, *[]string) {
+	dir := t.TempDir()
+	file := filepath.Join(dir, "token")
+	if err := os.WriteFile(file, []byte(toolsToken+"\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(file+".scopes", []byte(scopes+"\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	var seen []string
+	const repo = "/api/v1/repos/acme/app"
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		seen = append(seen, r.Method+" "+r.URL.Path)
+		if _, _, basic := r.BasicAuth(); basic || r.Header.Get("Authorization") != "token "+toolsToken {
+			http.Error(w, "unauthorized", 401)
+			return
+		}
+		if r.URL.Path == repo+"/branch_protections" {
+			http.Error(w, `{"message":"token does not have the administration of this repository"}`, 403)
+			return
+		}
+		if name := strings.TrimPrefix(r.URL.Path, repo+"/branches/"); r.Method == "GET" && name != r.URL.Path {
+			if rule, ok := protected[name]; ok {
+				_, _ = w.Write([]byte(`{"name":"` + name + `","commit":{"id":"c0"},"protected":true,"effective_branch_protection_name":"` + rule + `"}`))
+				return
+			}
+		}
+		r.SetBasicAuth("mesh-admin", f.password) // the fake's own door, past the token checked above
+		f.handle(w, r)
+	}))
+	t.Cleanup(srv.Close)
+	return &Forge{Client: forgehttp.Client{URL: srv.URL, TokenFile: file, Account: "mesh-tools"}}, &seen
+}
+
+func TestTheToolsAccountCommitsOnANewBranchWithItsTokenThoughTheRulesAreNotItsToRead(t *testing.T) {
+	f := newFake(t)
+	forge, _ := asTools(t, f, nil, "read:user,write:issue,write:repository for mesh-tools")
+	got, err := commit(context.Background(), forge, ask(t, map[string]any{"branch": "fix/365",
+		"files": filesArg(map[string]any{"path": "x", "content": "x"})}))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(f.writes) != 1 || !got.Created {
+		t.Fatalf("%d writes, %+v", len(f.writes), got)
+	}
+}
+
+func TestTheToolsAccountIsRefusedAProtectedBranchTheForgeSaysItGuardsAndTheDefaultBranch(t *testing.T) {
+	for branch, rule := range map[string]string{"release/1.0": "release/*", "fix/1-old": "fix/1-old", "main": ""} {
+		f := newFake(t)
+		protected := map[string]string{}
+		if rule != "" {
+			protected[branch] = rule
+		}
+		forge, _ := asTools(t, f, protected, "read:user,write:issue,write:repository for mesh-tools")
+		_, err := commit(context.Background(), forge, ask(t, map[string]any{"branch": branch,
+			"files": filesArg(map[string]any{"path": "x", "content": "x"})}))
+		if err == nil || !strings.Contains(err.Error(), "refused") || !strings.Contains(err.Error(), "ADR 0266") {
+			t.Errorf("%s: %v", branch, err)
+		}
+		if rule != "" && !strings.Contains(err.Error(), rule) {
+			t.Errorf("%s: the rule %s is not named: %v", branch, rule, err)
+		}
+		if len(f.writes)+len(f.patches) != 0 {
+			t.Errorf("%s: something was written", branch)
+		}
+	}
+}
+
+func TestATokenKeptForTheAdministratorIsNeverSent(t *testing.T) {
+	f := newFake(t)
+	// What the module kept before ADR 0365: the admin's token, its scopes line naming no account.
+	forge, seen := asTools(t, f, nil, "read:user,write:issue,write:repository")
+	_, err := commit(context.Background(), forge, ask(t, map[string]any{"branch": "fix/365",
+		"files": filesArg(map[string]any{"path": "x", "content": "x"})}))
+	if err == nil || !strings.Contains(err.Error(), "not mesh-tools's") {
+		t.Fatalf("%v", err)
+	}
+	if len(*seen) != 0 {
+		t.Fatalf("the forge was asked %v", *seen)
+	}
+}
+
+func TestTheBundleHandedATokenFileNeedsNoAdminLogin(t *testing.T) {
+	t.Setenv("MESH_GITEA_URL", "http://127.0.0.1:3000")
+	t.Setenv("MESH_GITEA_TOKEN_FILE", "/state/token")
+	t.Setenv("MESH_GITEA_TOOLS_USER", "")
+	t.Setenv("MESH_GITEA_ADMIN_USER", "")
+	t.Setenv("MESH_GITEA_ADMIN_PASSWORD_FILE", "")
+	f, err := ForgeFromEnv()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if f.TokenFile != "/state/token" || f.Account != "mesh-tools" || f.User != "" || f.PasswordFile != "" {
+		t.Fatalf("%+v", f.Client)
+	}
+}

modules/gitea/cmd/forge/commit.go

@@ -9,6 +9,8 @@ import (
 	"net/url"
 	"strings"
 	"unicode/utf8"
+
+	"gitea/internal/forgehttp"
 )
 
 // gitea_commit (novox/hq issue 375): one commit on a branch of its own, so an agent follows the branch / pull
@@ -33,6 +35,11 @@ type CommitAsk struct {
 	Message     string
 	Files       []FileChange
 	Patch       string // a unified diff, as git diff writes it, instead of Files
+	// PatchFile is the name of a file in the spool directory holding the patch (novox/hq issue 852), with the
+	// SHA-256 its caller says it has; commitAsk reads it into Patch.
+	PatchFile      string
+	PatchSHA256    string
+	patchFileGiven bool
 }
 
 // Committed is what gitea_commit made.
@@ -67,6 +74,11 @@ func readCommitAsk(args map[string]any) (CommitAsk, error) {
 	a := CommitAsk{Owner: text(args, "owner"), Repo: text(args, "repo"), Branch: text(args, "branch"),
 		Base: text(args, "base"), Message: strings.TrimSpace(raw(args, "message"))}
 	a.Patch = raw(args, "patch")
+	if v, ok := args["patch_file"]; ok && v != nil {
+		a.patchFileGiven = true
+		a.PatchFile = raw(args, "patch_file")
+	}
+	a.PatchSHA256 = strings.ToLower(strings.TrimSpace(raw(args, "patch_sha256")))
 	if a.Branch == "" {
 		return a, refuse("branch is required: the branch the commit goes on, a branch of its own (created from base when absent). Nothing was sent")
 	}
@@ -109,11 +121,23 @@ func readCommitAsk(args map[string]any) (CommitAsk, error) {
 			a.Files = append(a.Files, fc)
 		}
 	}
+	sources := 0
+	for _, g := range []bool{len(a.Files) > 0, strings.TrimSpace(a.Patch) != "", a.patchFileGiven} {
+		if g {
+			sources++
+		}
+	}
 	switch {
-	case len(a.Files) == 0 && strings.TrimSpace(a.Patch) == "":
-		return a, refuse("give files (each {path, content | content_base64 | delete: true}) or patch (a unified diff, as git diff writes it). Nothing was sent")
-	case len(a.Files) > 0 && strings.TrimSpace(a.Patch) != "":
-		return a, refuse("give files or patch, not both: one commit carries one of them. Nothing was sent")
+	case sources == 0:
+		return a, refuse("give files (each {path, content | content_base64 | delete: true}), patch (a unified diff, as git diff writes it) or patch_file (the name of a patch in the spool directory). Nothing was sent")
+	case sources > 1:
+		return a, refuse("give files, patch or patch_file, not more than one: one commit carries one of them. Nothing was sent")
+	case a.PatchSHA256 != "" && !a.patchFileGiven:
+		return a, refuse("patch_sha256 goes with patch_file only. Nothing was sent")
+	case a.patchFileGiven:
+		if err := checkPatchFileAsk(a); err != nil {
+			return a, err
+		}
 	case len(a.Files) > maxFiles:
 		return a, refuse("%d files is more than the %d one commit carries. Nothing was sent", len(a.Files), maxFiles)
 	case len(a.Patch) > maxPatchBytes:
@@ -132,13 +156,13 @@ func readCommitAsk(args map[string]any) (CommitAsk, error) {
 			return a, refuse("%s is named twice in files. Nothing was sent", fc.Path)
 		}
 		seen[fc.Path] = true
-		given := 0
+		have := 0
 		for _, g := range []bool{fc.Content != nil, fc.ContentBase64 != nil, fc.Delete} {
 			if g {
-				given++
+				have++
 			}
 		}
-		if given != 1 {
+		if have != 1 {
 			return a, refuse("files[%d] (%s) needs exactly one of content, content_base64 or delete: true. Nothing was sent", i, fc.Path)
 		}
 		if fc.Content != nil && !utf8.ValidString(*fc.Content) {
@@ -211,7 +235,32 @@ func commit(ctx context.Context, f *Forge, a CommitAsk) (*Committed, error) {
 	// Read the rules, or refuse: a branch the rules could not be read for is never written (fails closed).
 	var rules []Protection
 	if err := f.GetJSON(ctx, repo+"/branch_protections", &rules); err != nil {
-		return nil, fmt.Errorf("the protection rules of %s/%s could not be read, so the commit was not judged and nothing was sent: %w", a.Owner, a.Repo, err)
+		var status *forgehttp.StatusError
+		if !errors.As(err, &status) || status.Status != http.StatusForbidden {
+			return nil, fmt.Errorf("the protection rules of %s/%s could not be read, so the commit was not judged and nothing was sent: %w", a.Owner, a.Repo, err)
+		}
+		// The rules are a repository administrator's to read, and the tools' account is none (novox/hq ADR 0365
+		// §2). What it may read is the protection the forge applies to an existing branch: one protected is
+		// refused here. A branch not made yet is covered by no rule this account can see, and the forge itself
+		// judges the commit that makes it against every rule, refusing one a rule guards.
+		if err := targetRefused(a.Branch, r.DefaultBranch, nil); err != nil {
+			return nil, err
+		}
+		b, err := f.branch(ctx, repo, a.Branch)
+		if err != nil {
+			return nil, fmt.Errorf("whether a protection rule guards %s of %s/%s could not be read, so nothing was sent: %w", a.Branch, a.Owner, a.Repo, err)
+		}
+		if b != nil && b.Protected {
+			rule := b.Rule
+			if rule == "" {
+				rule = a.Branch
+			}
+			rules = []Protection{{RuleName: rule}}
+			if !ruleCovers(rule, a.Branch) {
+				return nil, refuse("a commit on %s is refused: the protection rule %s guards it (novox/hq ADR 0266). Put it on a "+
+					"branch of its own. Nothing was sent", a.Branch, rule)
+			}
+		}
 	}
 	if err := targetRefused(a.Branch, r.DefaultBranch, rules); err != nil {
 		return nil, err

modules/gitea/cmd/forge/forge.go

@@ -11,8 +11,8 @@ import (
 	"gitea/internal/forgehttp"
 )
 
-// The forge as this bundle reaches it: its own HTTP interface on the machine, as the forge's admin account
-// (internal/forgehttp, shared with the npm-registry bundle beside it).
+// The forge as this bundle reaches it: its own HTTP interface on the machine, as the tools' own account (novox/hq
+// ADR 0365 §2; internal/forgehttp, shared with the npm-registry bundle beside it).
 
 // Forge is the forge's HTTP interface.
 type Forge struct {
@@ -91,12 +91,15 @@ func (p Protection) name() string {
 	return p.BranchName
 }
 
-// Branch is one branch with the commit it points at.
+// Branch is one branch with the commit it points at, and the protection the forge applies to it: what an account
+// that may not read the rules themselves (the tools' account, novox/hq ADR 0365) knows of them.
 type Branch struct {
 	Name   string `json:"name"`
 	Commit struct {
 		ID string `json:"id"`
 	} `json:"commit"`
+	Protected bool   `json:"protected"`
+	Rule      string `json:"effective_branch_protection_name"`
 }
 
 // branch is the named branch, nil when the forge has none of that name.

modules/gitea/cmd/forge/forge_test.go

@@ -619,11 +619,17 @@ func TestToolsAreTheOnesTheReadmeNamesAndTheManifestBuilds(t *testing.T) {
 			if len(a.Loads) != 1 || a.Loads[0] != a.Binary {
 				t.Errorf("the bundle loads %v, not its binary %s", a.Loads, a.Binary)
 			}
-			for _, k := range []string{"MESH_GITEA_URL", "MESH_GITEA_ADMIN_USER", "MESH_GITEA_ADMIN_PASSWORD_FILE"} {
+			// The tools' own account, never the admin login (novox/hq ADR 0365 §2).
+			for _, k := range []string{"MESH_GITEA_URL", "MESH_GITEA_TOOLS_USER", "MESH_GITEA_TOKEN_FILE"} {
 				if a.Env[k] == "" {
 					t.Errorf("the bundle is not given %s", k)
 				}
 			}
+			for _, k := range []string{"MESH_GITEA_ADMIN_USER", "MESH_GITEA_ADMIN_PASSWORD_FILE"} {
+				if a.Env[k] != "" {
+					t.Errorf("the bundle is given %s: it acts as the tools' account, not the administrator", k)
+				}
+			}
 		}
 	}
 	if !found {

modules/gitea/cmd/forge/main.go

@@ -55,7 +55,9 @@ func Tools(forge func() (*Forge, error)) []stdio.Tool {
 				"the branch holds them — or patch, a unified diff as git diff writes it, which the forge applies. " +
 				"At most 200 files, 4 MiB each and 16 MiB together, or a 4 MiB patch. Answers the commit it made and " +
 				"the parent the forge made it on, read back from the branch, and says when the branch moved under " +
-				"it. Replaces git commit and git " +
+				"it. A patch too large to type goes as patch_file with patch_sha256: the name of a file in the " +
+				"spool directory (read once, applied as patch is, removed afterwards, never read from anywhere " +
+				"else). Replaces git commit and git " +
 				"push of a feature branch. (a)",
 			Input: map[string]any{
 				"type": "object",
@@ -79,7 +81,9 @@ func Tools(forge func() (*Forge, error)) []stdio.Tool {
 							"required": []string{"path"},
 						},
 					},
-					"patch": str("a unified diff of the change, as git diff or git format-patch writes it; give this or files"),
+					"patch":        str("a unified diff of the change, as git diff or git format-patch writes it; give this, patch_file or files"),
+					"patch_file":   str("for a patch too large to type: the NAME (32 to 64 characters of 0-9a-f, chosen at random by the caller, no path) of a file the caller wrote into the forge patch spool directory (the module's forge-patches directory); needs patch_sha256; give this, patch or files"),
+					"patch_sha256": str("with patch_file: the file's SHA-256, in hex; the commit is refused, and nothing is sent, when the file's differs"),
 				},
 				"required": []string{"owner", "repo", "branch", "message"},
 			},
@@ -88,7 +92,7 @@ func Tools(forge func() (*Forge, error)) []stdio.Tool {
 				if err != nil {
 					return nil, err
 				}
-				return commit(ctx, f, a)
+				return commitAsk(ctx, f, os.Getenv(patchDirEnv), a)
 			}),
 		},
 		{

modules/gitea/cmd/forge/patchfile.go

@@ -0,0 +1,109 @@
+package main
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"io"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"syscall"
+)
+
+// A patch too large to type into a call is handed over as a file (novox/hq issue 852). The caller writes it into
+// one spool directory the module declares (mode 0733: anyone writes, nobody lists) and names it in patch_file,
+// with the file's SHA-256. The tool runs as the machine's account, so it reads nothing but that directory: the
+// name is 32 to 64 characters of [0-9a-f], so it holds no separator and no dot; the file must be a regular file
+// (never a symlink); and its hash must be the caller's, because without the sticky bit another writer could have
+// replaced it. The file is removed once taken, whether the commit was made or not.
+
+const patchDirEnv = "MESH_GITEA_PATCH_DIR"
+
+var (
+	patchFileName = regexp.MustCompile(`^[0-9a-f]{32,64}$`)
+	patchSHA      = regexp.MustCompile(`^[0-9a-f]{64}$`)
+)
+
+// checkPatchFileAsk judges the arguments of a patch_file ask, before any file is looked at.
+func checkPatchFileAsk(a CommitAsk) error {
+	if !patchFileName.MatchString(a.PatchFile) {
+		return refuse("patch_file %q is not a name: 32 to 64 characters of 0-9a-f, no path (the file's name in the spool directory, chosen at random). Nothing was sent", a.PatchFile)
+	}
+	if !patchSHA.MatchString(a.PatchSHA256) {
+		return refuse("patch_file needs patch_sha256: the file's SHA-256, 64 hex characters. Nothing was sent")
+	}
+	return nil
+}
+
+// commitAsk makes the commit the ask names; a patch_file is first read from the spool directory into the patch
+// and removed afterwards.
+func commitAsk(ctx context.Context, f *Forge, spool string, a CommitAsk) (*Committed, error) {
+	if !a.patchFileGiven {
+		return commit(ctx, f, a)
+	}
+	if err := checkPatchFileAsk(a); err != nil {
+		return nil, err
+	}
+	if spool == "" {
+		return nil, refuse("patch_file is not available: %s is not set, so there is no spool directory. Nothing was sent", patchDirEnv)
+	}
+	path := filepath.Join(spool, a.PatchFile)
+	defer func() {
+		// Whatever happened, the file is not left: removing a symlink removes the link, never its target.
+		if st, err := os.Lstat(path); err == nil && !st.IsDir() {
+			_ = os.Remove(path)
+		}
+	}()
+	body, err := readSpooled(path, a.PatchFile)
+	if err != nil {
+		return nil, err
+	}
+	got := sha256.Sum256(body)
+	if hex.EncodeToString(got[:]) != a.PatchSHA256 {
+		return nil, refuse("the file %s is not the patch the caller hashed: its SHA-256 is %s, patch_sha256 says %s. Nothing was sent",
+			a.PatchFile, hex.EncodeToString(got[:]), a.PatchSHA256)
+	}
+	a.Patch = string(body)
+	return commit(ctx, f, a)
+}
+
+// readSpooled reads a regular file of at most maxPatchBytes, never through a symlink.
+func readSpooled(path, name string) ([]byte, error) {
+	st, err := os.Lstat(path)
+	switch {
+	case errors.Is(err, os.ErrNotExist):
+		return nil, refuse("patch_file %s: no such file in the spool directory. Nothing was sent", name)
+	case err != nil:
+		return nil, refuse("patch_file %s cannot be read: %v. Nothing was sent", name, err)
+	case !st.Mode().IsRegular():
+		return nil, refuse("patch_file %s is not a regular file (a symlink or a directory is never followed). Nothing was sent", name)
+	case st.Size() > maxPatchBytes:
+		return nil, refuse("patch_file %s is %s, more than the %s one commit carries: split it into several commits. Nothing was sent", name, mib(int(st.Size())), mib(maxPatchBytes))
+	}
+	fh, err := os.OpenFile(path, os.O_RDONLY|syscall.O_NOFOLLOW|syscall.O_NONBLOCK, 0)
+	if err != nil {
+		return nil, refuse("patch_file %s cannot be opened: %v. Nothing was sent", name, err)
+	}
+	defer fh.Close()
+	fst, err := fh.Stat()
+	if err != nil || !fst.Mode().IsRegular() {
+		return nil, refuse("patch_file %s is not a regular file. Nothing was sent", name)
+	}
+	// A hard link to a file elsewhere is no symlink, but it is not the caller's own file either.
+	if sys, ok := fst.Sys().(*syscall.Stat_t); !ok || sys.Nlink > 1 {
+		return nil, refuse("patch_file %s has more than one hard link: it must be a file of its own. Nothing was sent", name)
+	}
+	body, err := io.ReadAll(io.LimitReader(fh, maxPatchBytes+1))
+	switch {
+	case err != nil:
+		return nil, refuse("patch_file %s cannot be read: %v. Nothing was sent", name, err)
+	case len(body) > maxPatchBytes:
+		return nil, refuse("patch_file %s is more than the %s one commit carries: split it into several commits. Nothing was sent", name, mib(maxPatchBytes))
+	case strings.TrimSpace(string(body)) == "":
+		return nil, refuse("patch_file %s is empty. Nothing was sent", name)
+	}
+	return body, nil
+}

modules/gitea/cmd/forge/patchfile_test.go

@@ -0,0 +1,183 @@
+package main
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// novox/hq issue 852: a patch too large to type into a call is handed over as a file in one spool directory.
+
+const spoolName = "0123456789abcdef0123456789abcdef"
+const spoolPatch = "diff --git a/README.md b/README.md\n--- a/README.md\n+++ b/README.md\n@@ -1 +1 @@\n-hello\n+hi\n"
+
+func sum(s string) string { h := sha256.Sum256([]byte(s)); return hex.EncodeToString(h[:]) }
+
+func spoolWith(t *testing.T, name, content string) string {
+	t.Helper()
+	dir := t.TempDir()
+	if name != "" {
+		if err := os.WriteFile(filepath.Join(dir, name), []byte(content), 0o600); err != nil {
+			t.Fatal(err)
+		}
+	}
+	return dir
+}
+
+func fileAsk(t *testing.T, name, sha string) CommitAsk {
+	t.Helper()
+	return ask(t, map[string]any{"branch": "fix/9", "patch_file": name, "patch_sha256": sha})
+}
+
+func TestAPatchFileIsAppliedAsThePatchWouldBeAndTheFileIsGone(t *testing.T) {
+	f := newFake(t)
+	dir := spoolWith(t, spoolName, spoolPatch)
+	got, err := commitAsk(context.Background(), f.serve(), dir, fileAsk(t, spoolName, sum(spoolPatch)))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(f.patches) != 1 || f.patches[0]["content"] != spoolPatch || f.patches[0]["new_branch"] != "fix/9" || got.Commit != "p1" {
+		t.Fatalf("%v %+v", f.patches, got)
+	}
+	if _, err := os.Lstat(filepath.Join(dir, spoolName)); !os.IsNotExist(err) {
+		t.Fatalf("the file is still there: %v", err)
+	}
+}
+
+func TestAPatchFileIsRemovedWhenTheForgeRefusesIt(t *testing.T) {
+	f := newFake(t)
+	dir := spoolWith(t, spoolName, spoolPatch)
+	// the default branch is refused after the file was read
+	a := ask(t, map[string]any{"branch": "main", "patch_file": spoolName, "patch_sha256": sum(spoolPatch)})
+	if _, err := commitAsk(context.Background(), f.serve(), dir, a); err == nil {
+		t.Fatal("taken")
+	}
+	if _, err := os.Lstat(filepath.Join(dir, spoolName)); !os.IsNotExist(err) {
+		t.Fatalf("the file is still there: %v", err)
+	}
+}
+
+func TestAPatchFileThatCannotBeTakenIsRefusedBeforeAnythingIsSent(t *testing.T) {
+	outside := filepath.Join(t.TempDir(), "secret")
+	if err := os.WriteFile(outside, []byte(spoolPatch), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	type tc struct {
+		name  string
+		setup func(dir string)
+		file  string
+		sha   string
+		want  string
+	}
+	for _, c := range []tc{
+		{"wrong sha", func(d string) { _ = os.WriteFile(filepath.Join(d, spoolName), []byte(spoolPatch), 0o600) }, spoolName, sum("other"), "sha256"},
+		{"not found", func(string) {}, spoolName, sum(spoolPatch), "no such file"},
+		{"symlink", func(d string) { _ = os.Symlink(outside, filepath.Join(d, spoolName)) }, spoolName, sum(spoolPatch), "regular file"},
+		{"hard link", func(d string) { _ = os.Link(outside, filepath.Join(d, spoolName)) }, spoolName, sum(spoolPatch), "hard link"},
+		{"directory", func(d string) { _ = os.Mkdir(filepath.Join(d, spoolName), 0o700) }, spoolName, sum(spoolPatch), "regular file"},
+		{"too large", func(d string) {
+			_ = os.WriteFile(filepath.Join(d, spoolName), []byte(strings.Repeat("x", maxPatchBytes+1)), 0o600)
+		}, spoolName, sum(spoolPatch), "MiB"},
+		{"empty", func(d string) { _ = os.WriteFile(filepath.Join(d, spoolName), nil, 0o600) }, spoolName, sum(""), "empty"},
+	} {
+		f := newFake(t)
+		dir := t.TempDir()
+		c.setup(dir)
+		_, err := commitAsk(context.Background(), f.serve(), dir, fileAsk(t, c.file, c.sha))
+		if err == nil || !strings.Contains(err.Error(), c.want) || !strings.Contains(err.Error(), "Nothing was sent") {
+			t.Errorf("%s: %v", c.name, err)
+		}
+		if len(f.patches)+len(f.writes) != 0 {
+			t.Errorf("%s: something was sent", c.name)
+		}
+	}
+	if b, err := os.ReadFile(outside); err != nil || string(b) != spoolPatch {
+		t.Errorf("the file outside the spool was touched: %v", err)
+	}
+}
+
+func TestAPatchFileAskThatCannotBeReadIsRefused(t *testing.T) {
+	ok := sum(spoolPatch)
+	for name, args := range map[string]map[string]any{
+		"no sha":         {"patch_file": spoolName},
+		"sha not hex":    {"patch_file": spoolName, "patch_sha256": strings.Repeat("z", 64)},
+		"sha too short":  {"patch_file": spoolName, "patch_sha256": ok[:63]},
+		"empty name":     {"patch_file": "", "patch_sha256": ok, "files": filesArg()},
+		"dotdot":         {"patch_file": "../" + spoolName, "patch_sha256": ok},
+		"slash":          {"patch_file": "a/" + spoolName, "patch_sha256": ok},
+		"absolute":       {"patch_file": "/etc/passwd", "patch_sha256": ok},
+		"too short":      {"patch_file": strings.Repeat("a", 31), "patch_sha256": ok},
+		"too long":       {"patch_file": strings.Repeat("a", 65), "patch_sha256": ok},
+		"upper case":     {"patch_file": strings.ToUpper(spoolName), "patch_sha256": ok},
+		"not hex":        {"patch_file": strings.Repeat("g", 32), "patch_sha256": ok},
+		"with patch":     {"patch_file": spoolName, "patch_sha256": ok, "patch": "diff"},
+		"with files":     {"patch_file": spoolName, "patch_sha256": ok, "files": filesArg(map[string]any{"path": "x", "content": "x"})},
+		"sha without it": {"patch": "diff", "patch_sha256": ok},
+	} {
+		full := map[string]any{"owner": "acme", "repo": "app", "message": "m", "branch": "b"}
+		for k, v := range args {
+			full[k] = v
+		}
+		_, err := readCommitAsk(full)
+		if err == nil || !strings.Contains(err.Error(), "Nothing was sent") {
+			t.Errorf("%s: %v", name, err)
+		}
+	}
+	// 64 characters is taken; so is an upper-case sha.
+	for _, n := range []string{spoolName, strings.Repeat("ab", 32)} {
+		if _, err := readCommitAsk(map[string]any{"owner": "acme", "repo": "app", "message": "m", "branch": "b",
+			"patch_file": n, "patch_sha256": strings.ToUpper(sum(spoolPatch))}); err != nil {
+			t.Errorf("%s: %v", n, err)
+		}
+	}
+}
+
+func TestAPatchFileWithoutASpoolDirectoryIsRefused(t *testing.T) {
+	f := newFake(t)
+	_, err := commitAsk(context.Background(), f.serve(), "", fileAsk(t, spoolName, sum(spoolPatch)))
+	if err == nil || !strings.Contains(err.Error(), "MESH_GITEA_PATCH_DIR") || !strings.Contains(err.Error(), "Nothing was sent") {
+		t.Fatalf("%v", err)
+	}
+}
+
+func TestTheManifestDeclaresTheSpoolDirectoryAndGivesItToTheBundle(t *testing.T) {
+	raw, err := os.ReadFile("../../module.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var m struct {
+		Resources []struct {
+			ID, Type, Path, Mode, Owner string
+		} `json:"resources"`
+		Build struct {
+			Artifacts []struct {
+				From string            `json:"from"`
+				Env  map[string]string `json:"env"`
+			} `json:"artifacts"`
+		} `json:"build"`
+	}
+	if err := jsonInto(raw, &m); err != nil {
+		t.Fatal(err)
+	}
+	found := false
+	for _, r := range m.Resources {
+		if r.ID == "forge-patches" {
+			found = true
+			if r.Type != "directory" || r.Mode != "0733" || r.Owner != "${machine:account}" || r.Path == "" {
+				t.Errorf("%+v", r)
+			}
+		}
+	}
+	if !found {
+		t.Error("no forge-patches directory")
+	}
+	for _, a := range m.Build.Artifacts {
+		if a.From == "cmd/forge" && a.Env["MESH_GITEA_PATCH_DIR"] != "${dir:forge-patches}" {
+			t.Errorf("env %v", a.Env)
+		}
+	}
+}

modules/gitea/cmd/forge/templates_test.go

@@ -0,0 +1,64 @@
+package main
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// The module's directory, where its manifest and its files/ are.
+const moduleDir = "../.."
+
+// templateText is the text a file resource places on the machine: its template's, in the module's files/
+// (novox/hq ADR 0349 §2). A resource that names no template, or a template that is not there, fails the test.
+func templateText(t *testing.T, r map[string]any) string {
+	t.Helper()
+	name, _ := r["template"].(string)
+	if name == "" {
+		t.Fatalf("resource %v names no template", r["id"])
+	}
+	raw, err := os.ReadFile(filepath.Join(moduleDir, filepath.FromSlash(name)))
+	if err != nil {
+		t.Fatalf("resource %v names %s: %v", r["id"], name, err)
+	}
+	return string(raw)
+}
+
+// No file resource carries its text inline: each names its template in files/, and the build packs files/
+// into the one archive the controller reads the templates back from (novox/hq ADR 0349 §2).
+func TestEveryFileTakesItsTextFromATemplate(t *testing.T) {
+	raw, err := os.ReadFile(filepath.Join(moduleDir, "module.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	var m struct {
+		Resources []map[string]any `json:"resources"`
+		Build     struct {
+			Artifacts []map[string]any `json:"artifacts"`
+		} `json:"build"`
+	}
+	if err := json.Unmarshal(raw, &m); err != nil {
+		t.Fatal(err)
+	}
+	for _, r := range m.Resources {
+		if _, inline := r["content"]; inline {
+			t.Errorf("resource %v keeps its text inline: keep it in files/ and name it as the template", r["id"])
+		}
+		if r["type"] == "file" {
+			templateText(t, r)
+		}
+	}
+	packs := 0
+	for _, a := range m.Build.Artifacts {
+		if a["kind"] == "archive" && a["from"] == "files" {
+			packs++
+			if a["name"] != "files" {
+				t.Errorf("the templates archive is named %v, not files", a["name"])
+			}
+		}
+	}
+	if packs != 1 {
+		t.Errorf("the build packs files/ into %d archives, not one", packs)
+	}
+}