Describe the signature scheme in docs/FORMAT.md as the code builds it (closes #187)

The Signature Scheme section now states what signatureString builds: the
magic, the outer uuid as lower-case hex with no hyphens, and the outer
sha256 as the lower-case hex of its multihash, which starts 1220, with an
example string taken from a run of the code. It says signer is the
upper-case hex fingerprint of the signing primary key and that a signature
is stored only in the manifest. The mf.proto comments on fields 201 to 203
say the same, and mf.pb.go is regenerated. A new test pins the example
string. Nothing about what is signed or how changes.

Model: opus-5-5

internal/cli/entry_test.go

@@ -1664,119 +1664,20 @@ func TestGenerateValidatesInputPaths(t *testing.T) {
 	})
 }
 
-// generateTestDir writes testFile1 and runs gen on testDir, which writes
+// TestFlagAfterArgumentIsArgument asserts that flags are read only before a
-// the manifest to testDir/index.mf.
+// command's first argument: after it, -v is a path, not the verbose flag.
-func generateTestDir(t *testing.T, fs afero.Fs) {
+func TestFlagAfterArgumentIsArgument(t *testing.T) {
-	t.Helper()
-
-	require.NoError(t, fs.MkdirAll(testDir, 0o755))
-	writeTestFile(t, fs, testFile1, "content")
-
-	opts := testOpts([]string{testApp, cmdGenerate, "-q", testDir}, fs)
-	require.Equal(t, 0, runCLI(opts), testStderr(t, opts))
-}
-
-// TestCheckReadsOptionAfterPath runs check on an unsigned manifest with
-// --require-signature after the directory. check must refuse the manifest.
-func TestCheckReadsOptionAfterPath(t *testing.T) {
 	t.Parallel()
 
 	fs := afero.NewMemMapFs()
-	generateTestDir(t, fs)
+	require.NoError(t, fs.MkdirAll(testDir, 0o755))
+	writeTestFile(t, fs, testFile1, "content")
 
-	opts := testOpts([]string{
+	opts := testOpts([]string{testApp, cmdGenerate, testDir, "-v"}, fs)
-		testApp, cmdCheck, "-q", testDir, "--" + flagRequireSignature, msgFpA,
+	exitCode := runCLI(opts)
-	}, fs)
-	assert.Equal(t, 1, runCLI(opts))
-	assert.Contains(t, testStderr(t, opts), "manifest is not signed")
-}
 
-// TestFreshenReadsOptionAfterPath runs freshen with --include-permissions
+	assert.Equal(t, 1, exitCode)
-// after the directory. freshen must record the file's mode.
+	assert.Contains(t, testStderr(t, opts), "path does not exist: -v")
-func TestFreshenReadsOptionAfterPath(t *testing.T) {
-	t.Parallel()
-
-	fs := afero.NewOsFs()
-	root, manifestPath := setupFreshenDir(t, fs,
-		map[string]string{testFileTxt: "a file"})
-	require.NoError(t, fs.Chmod(filepath.Join(root, testFileTxt), 0o640))
-
-	opts := testOpts([]string{
-		testApp, cmdFreshen, "-q", root, "--" + flagIncludePermissions,
-	}, fs)
-	require.Equal(t, 0, runCLI(opts), testStderr(t, opts))
-
-	files := manifestFiles(t, fs, manifestPath)
-	require.Len(t, files, 1)
-	assert.Equal(t, uint32(0o640), files[0].GetMode())
-}
-
-// TestFetchReadsOptionAfterURL runs fetch with --dest after the URL. The
-// file and the manifest must land in that directory and nothing in the
-// current one.
-//
-//nolint:paralleltest // changes the process-global working directory
-func TestFetchReadsOptionAfterURL(t *testing.T) {
-	content := []byte("fetched")
-	manifest := manifestOf(t, map[string][]byte{testFileTxt: content})
-
-	server := httptest.NewServer(fetchTestHandler(manifest,
-		map[string][]byte{testFileTxt: content}))
-	defer server.Close()
-
-	cwd := chdirTemp(t)
-	dest := t.TempDir()
-
-	opts := testOpts([]string{
-		testApp, cmdFetch, "-q", server.URL, "--" + flagDest, dest,
-	}, afero.NewOsFs())
-	require.Equal(t, 0, runCLI(opts), testStderr(t, opts))
-
-	assert.Equal(t,
-		map[string][]byte{testFileTxt: content, defaultManifestName: manifest},
-		filesUnder(t, dest))
-	assert.Empty(t, filesUnder(t, cwd), "fetch wrote outside --dest")
-}
-
-// TestOneArgumentCommandsRefuseSecond runs each command that takes one
-// argument with two. It must fail naming the second.
-func TestOneArgumentCommandsRefuseSecond(t *testing.T) {
-	t.Parallel()
-
-	for _, command := range []string{
-		cmdCheck, cmdFreshen, cmdList, cmdExport, cmdFetch,
-	} {
-		t.Run(command, func(t *testing.T) {
-			t.Parallel()
-
-			fs := afero.NewMemMapFs()
-			generateTestDir(t, fs)
-
-			opts := testOpts([]string{testApp, command, testDir, "/second"}, fs)
-			assert.Equal(t, 1, runCLI(opts))
-			assert.Contains(t, testStderr(t, opts),
-				`unexpected argument "/second"`)
-		})
-	}
-}
-
-// TestGenerateReadsPathAfterDoubleDash runs gen -- -x where -x is a
-// directory. -x must be read as the path to list, not as an option.
-//
-//nolint:paralleltest // changes the process-global working directory
-func TestGenerateReadsPathAfterDoubleDash(t *testing.T) {
-	chdirTemp(t)
-
-	fs := afero.NewOsFs()
-	require.NoError(t, fs.Mkdir("-x", 0o755))
-	writeTestFile(t, fs, filepath.Join("-x", testFileTxt), "content")
-
-	opts := testOpts([]string{testApp, cmdGenerate, "-q", "--", "-x"}, fs)
-	require.Equal(t, 0, runCLI(opts), testStderr(t, opts))
-
-	files := manifestFiles(t, fs, filepath.Join("-x", defaultManifestName))
-	require.Len(t, files, 1)
-	assert.Equal(t, testFileTxt, files[0].GetPath())
 }
 
 func TestCheckDetectsManifestCorruption(t *testing.T) {

internal/cli/mfer.go

@@ -48,10 +48,6 @@ func manifestTempPath(out string) string {
 // errUnknownCommand indicates an unrecognized command argument.
 var errUnknownCommand = errors.New("unknown command")
 
-// errUnexpectedArgument indicates a second argument to a command that takes
-// one.
-var errUnexpectedArgument = errors.New("unexpected argument")
-
 // CLIApp is the main CLI application container. It holds configuration,
 // I/O streams, and filesystem abstraction to enable testing and flexibility.
 //
@@ -158,14 +154,13 @@ func commonFlags() []cli.Flag {
 	}
 }
 
-// refuseExtraArgs is the ArgValidator of the commands that take one
+// stopOnFirstArg returns the StopOnNthArg setting every command uses: flags
-// argument: it refuses a second one, naming it.
+// are read only before the command's first argument, and everything after it
-func refuseExtraArgs(_ context.Context, cmd *cli.Command) error {
+// is an argument, as with urfave/cli v2. So `mfer gen d -v` names a path "-v".
-	if cmd.Args().Len() > 1 {
+func stopOnFirstArg() *int {
-		return fmt.Errorf("%w %q", errUnexpectedArgument, cmd.Args().Get(1))
+	n := 1
-	}
 
-	return nil
+	return &n
 }
 
 // requireSignatureFlag returns the --require-signature flag taken by the
@@ -191,10 +186,11 @@ func includePermissionsFlag() *cli.BoolFlag {
 
 func (mfa *CLIApp) generateCommand() *cli.Command {
 	return &cli.Command{
-		Name:      cmdGenerate,
+		Name:         cmdGenerate,
-		Aliases:   []string{"gen"},
+		Aliases:      []string{"gen"},
-		Usage:     "Generate manifest file",
+		Usage:        "Generate manifest file",
-		ArgsUsage: "[path ...]",
+		ArgsUsage:    "[path ...]",
+		StopOnNthArg: stopOnFirstArg(),
 		Action: func(ctx context.Context, cmd *cli.Command) error {
 			mfa.setVerbosity(cmd)
 			mfa.printBanner()
@@ -256,7 +252,7 @@ func (mfa *CLIApp) checkCommand() *cli.Command {
 		Name:         cmdCheck,
 		Usage:        "Validate files using manifest file",
 		ArgsUsage:    manifestArgsUsage,
-		ArgValidator: refuseExtraArgs,
+		StopOnNthArg: stopOnFirstArg(),
 		Action: func(ctx context.Context, cmd *cli.Command) error {
 			mfa.setVerbosity(cmd)
 			mfa.printBanner()
@@ -290,7 +286,7 @@ func (mfa *CLIApp) freshenCommand() *cli.Command {
 		Name:         cmdFreshen,
 		Usage:        "Update manifest with changed, new, and removed files",
 		ArgsUsage:    manifestArgsUsage,
-		ArgValidator: refuseExtraArgs,
+		StopOnNthArg: stopOnFirstArg(),
 		Action: func(ctx context.Context, cmd *cli.Command) error {
 			mfa.setVerbosity(cmd)
 			mfa.printBanner()
@@ -341,7 +337,7 @@ func (mfa *CLIApp) exportCommand() *cli.Command {
 		Name:         cmdExport,
 		Usage:        "Export manifest contents as JSON",
 		ArgsUsage:    "[manifest file or URL]",
-		ArgValidator: refuseExtraArgs,
+		StopOnNthArg: stopOnFirstArg(),
 		Action: func(ctx context.Context, cmd *cli.Command) error {
 			mfa.setVerbosity(cmd)
 
@@ -352,8 +348,9 @@ func (mfa *CLIApp) exportCommand() *cli.Command {
 
 func (mfa *CLIApp) versionCommand() *cli.Command {
 	return &cli.Command{
-		Name:  cmdVersion,
+		Name:         cmdVersion,
-		Usage: "Show version",
+		Usage:        "Show version",
+		StopOnNthArg: stopOnFirstArg(),
 		Action: func(context.Context, *cli.Command) error {
 			mfa.printVersion()
 
@@ -368,7 +365,7 @@ func (mfa *CLIApp) listCommand() *cli.Command {
 		Aliases:      []string{"ls"},
 		Usage:        "List files in manifest",
 		ArgsUsage:    manifestArgsUsage,
-		ArgValidator: refuseExtraArgs,
+		StopOnNthArg: stopOnFirstArg(),
 		Action:       mfa.listManifestOperation,
 		Flags: []cli.Flag{
 			&cli.BoolFlag{
@@ -389,7 +386,7 @@ func (mfa *CLIApp) fetchCommand() *cli.Command {
 		Name:         cmdFetch,
 		Usage:        "fetch manifest and referenced files",
 		ArgsUsage:    "URL",
-		ArgValidator: refuseExtraArgs,
+		StopOnNthArg: stopOnFirstArg(),
 		Action: func(ctx context.Context, cmd *cli.Command) error {
 			mfa.setVerbosity(cmd)
 			mfa.printBanner()
@@ -448,8 +445,9 @@ func (mfa *CLIApp) run(args []string) {
 		Writer:                mfa.Stdout,
 		// v3 writes its "Incorrect Usage" line to ErrWriter; v2 wrote it to
 		// stdout, before the help, so it stays on stdout.
-		ErrWriter: mfa.Stdout,
+		ErrWriter:    mfa.Stdout,
-		Flags:     commonFlags(),
+		Flags:        commonFlags(),
+		StopOnNthArg: stopOnFirstArg(),
 		Action: func(_ context.Context, cmd *cli.Command) error {
 			if cmd.Args().Len() > 0 {
 				return fmt.Errorf("%w %q", errUnknownCommand, cmd.Args().First())

mfer/mf.pb.go

@@ -224,9 +224,9 @@ type MFFileOuter struct {
 	Uuid         []byte `protobuf:"bytes,105,opt,name=uuid,proto3" json:"uuid,omitempty"`
 	InnerMessage []byte `protobuf:"bytes,199,opt,name=innerMessage,proto3" json:"innerMessage,omitempty"`
 	// one OpenPGP signature, armored or binary, over the canonical string
-	// ZNAVSRFG-<uuid>-<sha256 as a multihash>, with the uuid as 32
+	// ZNAVSRFG-<uuid>-<multihash of sha256>, with the uuid and the
-	// lower-case hex digits and no hyphens, and the multihash in lower-case
+	// multihash in lower-case hex (see docs/FORMAT.md). A signature is
-	// hex (see docs/FORMAT.md). A signature is never stored anywhere else.
+	// never stored anywhere else.
 	Signature []byte `protobuf:"bytes,201,opt,name=signature,proto3,oneof" json:"signature,omitempty"`
 	// fingerprint of the signing primary key, in upper-case hex
 	Signer []byte `protobuf:"bytes,202,opt,name=signer,proto3,oneof" json:"signer,omitempty"`

mfer/mf.proto

@@ -36,9 +36,9 @@ message MFFileOuter {
     // 2xx for optional manifest root attributes
 
     // one OpenPGP signature, armored or binary, over the canonical string
-    // ZNAVSRFG-<uuid>-<sha256 as a multihash>, with the uuid as 32
+    // ZNAVSRFG-<uuid>-<multihash of sha256>, with the uuid and the
-    // lower-case hex digits and no hyphens, and the multihash in lower-case
+    // multihash in lower-case hex (see docs/FORMAT.md). A signature is
-    // hex (see docs/FORMAT.md). A signature is never stored anywhere else.
+    // never stored anywhere else.
     optional bytes signature = 201;
     // fingerprint of the signing primary key, in upper-case hex
     optional bytes signer = 202;

mfer/mf.proto.sha256

@@ -1 +1 @@
-4f8ea5276a8e66590e71ed154a9176b0f68ffa9ab69d8de5aff0e0d9b731164d  mf.proto
+1304a5d944dc272e07b01b2b74c7fdfd3a478ff75efe9f5978cb2d513a5063bc  mf.proto