Simplify the V4 storage-first ceremony protocol

cmd/mpc-ceremony/atomic_output.go

@@ -0,0 +1,60 @@
+package main
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"slices"
+)
+
+// writeAtomicOutputDir publishes a small closed set of result files with a
+// no-replace directory rename. A byte-identical completed result is an
+// idempotent success; incomplete or conflicting output is never overwritten.
+func writeAtomicOutputDir(outDir string, files map[string][]byte) (err error) {
+	parent := filepath.Dir(outDir)
+	if err := os.MkdirAll(parent, 0o700); err != nil {
+		return err
+	}
+	if _, err := os.Lstat(outDir); err == nil {
+		info, statErr := os.Lstat(outDir)
+		if statErr != nil || info.Mode()&os.ModeSymlink != 0 || !info.IsDir() {
+			return errors.New("atomic output path exists but is not a regular directory")
+		}
+		for name, expected := range files {
+			actual, readErr := readRegularOperationalFile(filepath.Join(outDir, name), maxOperationalRecordBytes)
+			if readErr != nil || !slices.Equal(actual, expected) {
+				return errors.New("atomic output already exists with conflicting or incomplete contents")
+			}
+		}
+		entries, readErr := os.ReadDir(outDir)
+		if readErr != nil || len(entries) != len(files) {
+			return errors.New("atomic output already exists with conflicting or incomplete contents")
+		}
+		return nil
+	} else if !os.IsNotExist(err) {
+		return err
+	}
+	tmp, err := os.MkdirTemp(parent, ".atomic-output-*")
+	if err != nil {
+		return err
+	}
+	complete := false
+	defer func() {
+		if !complete {
+			_ = os.RemoveAll(tmp)
+		}
+	}()
+	for name, data := range files {
+		if err := writeFreshOperationalFile(filepath.Join(tmp, name), data, 0o600); err != nil {
+			return err
+		}
+	}
+	if err := syncDirectory(tmp); err != nil {
+		return err
+	}
+	if err := renameDirectoryNoReplace(tmp, outDir); err != nil {
+		return err
+	}
+	complete = true
+	return syncDirectory(parent)
+}

cmd/mpc-ceremony/atomic_output_test.go

@@ -0,0 +1,36 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestAtomicOutputDirectoryIsIdempotentAndClosed(t *testing.T) {
+	out := filepath.Join(t.TempDir(), "result")
+	files := map[string][]byte{"checkpoint.json": []byte("checkpoint"), "checkpoint.sig": []byte("signature")}
+	if err := writeAtomicOutputDir(out, files); err != nil {
+		t.Fatal(err)
+	}
+	if err := writeAtomicOutputDir(out, files); err != nil {
+		t.Fatalf("byte-identical retry: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join(out, "checkpoint.sig"), []byte("changed"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := writeAtomicOutputDir(out, files); err == nil || !strings.Contains(err.Error(), "conflicting or incomplete") {
+		t.Fatalf("conflicting retry = %v", err)
+	}
+}
+
+func TestAtomicOutputFailureDoesNotPublishDirectory(t *testing.T) {
+	parent := t.TempDir()
+	out := filepath.Join(parent, "result")
+	if err := writeAtomicOutputDir(out, map[string][]byte{"nested/file": []byte("invalid")}); err == nil {
+		t.Fatal("invalid nested output succeeded")
+	}
+	if _, err := os.Lstat(out); !os.IsNotExist(err) {
+		t.Fatalf("failed output was published: %v", err)
+	}
+}

cmd/mpc-ceremony/checkpoint_command.go

@@ -28,6 +28,15 @@ type builtCheckpointEvidence struct {
 	request    mpcceremony.CheckpointSigningRequest
 }
 
+type checkpointAcceptanceSigner func(
+	trusted *mpcceremony.TrustedCeremony,
+	checkpoint mpcceremony.Checkpoint,
+	slot mpcceremony.CheckpointSubmissionSlot,
+	envelope mpcceremony.SubmissionEnvelopeV1,
+	envelopeRefs mpcceremony.SignedArtifactRefs,
+	manifest mpcceremony.ArtifactRef,
+) ([]byte, []byte, mpcceremony.SignedArtifactRefs, error)
+
 func parseCheckpoint(invocation Invocation, args []string) (Invocation, error) {
 	if len(args) == 0 {
 		return Invocation{}, &usageError{message: "missing checkpoint command", topic: []string{"checkpoint"}}
@@ -36,6 +45,14 @@ func parseCheckpoint(invocation Invocation, args []string) (Invocation, error) {
 		return Invocation{}, &helpRequest{topic: append([]string{"checkpoint"}, args[1:]...)}
 	}
 	switch args[0] {
+	case "verify-release-v4":
+		options, err := parseEvidenceV4(CommandCheckpointVerifyReleaseV4, args[1:])
+		invocation.Command, invocation.Options = CommandCheckpointVerifyReleaseV4, options
+		return invocation, wrapCommandError(err, "checkpoint", args[0])
+	case "prepare-v4", "sign-v4", "initialize-v4", "record-v4", "allocate-v4", "accept-candidate-v4", "reject-candidate-v4", "verify-stored-v4", "inspect-signed-v4", "inspect-enrollments-v4":
+		options, err := parseCheckpointV4(args[0], args[1:])
+		invocation.Command, invocation.Options = Command("checkpoint "+args[0]), options
+		return invocation, wrapCommandError(err, "checkpoint", args[0])
 	case "prepare":
 		options, err := parseCheckpointPrepare(args[1:])
 		invocation.Command, invocation.Options = CommandCheckpointPrepare, options
@@ -580,6 +597,9 @@ func buildCheckpointEvidenceWithParent(options CheckpointEvidenceOptions, verify
 	if err != nil {
 		return builtCheckpointEvidence{}, err
 	}
+	if trusted.Definition.Schema == mpcceremony.DefinitionSchemaV4 {
+		return builtCheckpointEvidence{}, errors.New("definition v4 requires the explicit V4 checkpoint commands")
+	}
 	definitionRefs, err := checkpointPairRefs(options.ArtifactRoot, options.CeremonyPath, options.CeremonySignaturePath)
 	if err != nil {
 		return builtCheckpointEvidence{}, fmt.Errorf("definition references: %w", err)
@@ -1372,7 +1392,7 @@ func buildPhase1ClosedCheckpoint(options CheckpointEvidenceOptions, trusted *mpc
 }
 
 func checkpointSchemaForDefinition(definition mpcceremony.CeremonyDefinition) string {
-	if definition.Schema == mpcceremony.DefinitionSchema {
+	if definition.Schema == mpcceremony.DefinitionSchemaV3 {
 		return mpcceremony.CheckpointSchema
 	}
 	return mpcceremony.CheckpointSchemaV1
@@ -1446,21 +1466,33 @@ func buildReceiptCheckpoint(options CheckpointEvidenceOptions, trusted *mpccerem
 	if err != nil {
 		return builtCheckpointEvidence{}, err
 	}
+	if err := requireSubmissionEnvelopeNames(slot, envelopeRefs); err != nil {
+		return builtCheckpointEvidence{}, err
+	}
 	envelope, err := mpcceremony.VerifySignedSubmissionEnvelope(trusted.Definition, previous, slot, envelopeBytes, envelopeSignatureBytes)
 	if err != nil {
 		return builtCheckpointEvidence{}, err
 	}
 	if envelope.Kind != mpcceremony.CheckpointSubmissionReceipt {
 		return builtCheckpointEvidence{}, errors.New("receipt-accepted checkpoint requires a receipt submission envelope")
 	}
+	if err := requireReceiptPayloadNames(slot, envelope.Payloads); err != nil {
+		return builtCheckpointEvidence{}, err
+	}
 	if err := verifyReceiptEnvelopePayloads(options.ArtifactRoot, trusted, previous, envelope); err != nil {
 		return builtCheckpointEvidence{}, err
 	}
 	manifestBytes, manifest, err := checkpointArtifactBytes(options.ArtifactRoot, options.ManifestPath, maxOperationalRecordBytes)
 	if err != nil {
 		return builtCheckpointEvidence{}, fmt.Errorf("submission manifest: %w", err)
 	}
-	ackBytes, ackSignatureBytes, ackRefs, err := checkpointSignedBytes(options.ArtifactRoot, options.AcknowledgementPath, options.AcknowledgementSignaturePath)
+	var ackBytes, ackSignatureBytes []byte
+	var ackRefs mpcceremony.SignedArtifactRefs
+	if options.AcceptanceSigner != nil {
+		ackBytes, ackSignatureBytes, ackRefs, err = options.AcceptanceSigner(trusted, previous, slot, envelope, envelopeRefs, manifest)
+	} else {
+		ackBytes, ackSignatureBytes, ackRefs, err = checkpointAcknowledgementBytes(options)
+	}
 	if err != nil {
 		return builtCheckpointEvidence{}, fmt.Errorf("submission acknowledgement: %w", err)
 	}
@@ -1539,6 +1571,9 @@ func buildCandidateCheckpoint(options CheckpointEvidenceOptions, trusted *mpccer
 	if err != nil {
 		return builtCheckpointEvidence{}, err
 	}
+	if err := requireSubmissionEnvelopeNames(slot, envelopeRefs); err != nil {
+		return builtCheckpointEvidence{}, err
+	}
 	if slot.Kind != mpcceremony.CheckpointSubmissionCandidate {
 		return builtCheckpointEvidence{}, errors.New("candidate-accepted checkpoint requires a candidate submission slot")
 	}
@@ -1558,7 +1593,13 @@ func buildCandidateCheckpoint(options CheckpointEvidenceOptions, trusted *mpccer
 	if err != nil {
 		return builtCheckpointEvidence{}, fmt.Errorf("candidate manifest: %w", err)
 	}
-	ackBytes, ackSignatureBytes, ackRefs, err := checkpointSignedBytes(options.ArtifactRoot, options.AcknowledgementPath, options.AcknowledgementSignaturePath)
+	var ackBytes, ackSignatureBytes []byte
+	var ackRefs mpcceremony.SignedArtifactRefs
+	if options.AcceptanceSigner != nil {
+		ackBytes, ackSignatureBytes, ackRefs, err = options.AcceptanceSigner(trusted, previous, slot, envelope, envelopeRefs, manifest)
+	} else {
+		ackBytes, ackSignatureBytes, ackRefs, err = checkpointAcknowledgementBytes(options)
+	}
 	if err != nil {
 		return builtCheckpointEvidence{}, fmt.Errorf("candidate acknowledgement: %w", err)
 	}
@@ -1787,6 +1828,29 @@ func findAllocatedSubmission(checkpoint mpcceremony.Checkpoint, envelope mpccere
 	return mpcceremony.CheckpointSubmissionSlot{}, errors.New("submission envelope does not match an allocated checkpoint slot")
 }
 
+func requireSubmissionEnvelopeNames(slot mpcceremony.CheckpointSubmissionSlot, refs mpcceremony.SignedArtifactRefs) error {
+	base := strings.TrimSuffix(slot.ManifestKey, "/manifest.json")
+	if refs.Record.Name != base+"/envelope.json" || refs.Signature.Name != base+"/envelope.sig" {
+		return errors.New("submission envelope does not use the preallocated storage path")
+	}
+	return nil
+}
+
+func requireReceiptPayloadNames(slot mpcceremony.CheckpointSubmissionSlot, refs []mpcceremony.ArtifactRef) error {
+	base := fmt.Sprintf("%s/custody/%04d", slot.Phase, slot.Index)
+	want := []string{base + "/outbound-receipt.json", base + "/outbound-receipt.sig"}
+	got := make([]string, len(refs))
+	for i := range refs {
+		got[i] = refs[i].Name
+	}
+	slices.Sort(got)
+	slices.Sort(want)
+	if !slices.Equal(got, want) {
+		return errors.New("receipt submission does not use the deterministic ceremony evidence paths")
+	}
+	return nil
+}
+
 func checkpointSignedBytes(root, recordPath, signaturePath string) ([]byte, []byte, mpcceremony.SignedArtifactRefs, error) {
 	recordBytes, recordRef, err := checkpointArtifactBytes(root, recordPath, maxOperationalRecordBytes)
 	if err != nil {
@@ -1800,6 +1864,31 @@ func checkpointSignedBytes(root, recordPath, signaturePath string) ([]byte, []by
 	return recordBytes, signatureBytes, refs, nil
 }
 
+func checkpointAcknowledgementBytes(options CheckpointEvidenceOptions) ([]byte, []byte, mpcceremony.SignedArtifactRefs, error) {
+	if options.AcknowledgementRecordName == "" && options.AcknowledgementSignatureName == "" {
+		return checkpointSignedBytes(options.ArtifactRoot, options.AcknowledgementPath, options.AcknowledgementSignaturePath)
+	}
+	if options.AcknowledgementRecordName == "" || options.AcknowledgementSignatureName == "" {
+		return nil, nil, mpcceremony.SignedArtifactRefs{}, errors.New("both intended acknowledgement names are required")
+	}
+	record, err := readRegularOperationalFile(options.AcknowledgementPath, maxOperationalRecordBytes)
+	if err != nil {
+		return nil, nil, mpcceremony.SignedArtifactRefs{}, err
+	}
+	signature, err := readRegularOperationalFile(options.AcknowledgementSignaturePath, 4096)
+	if err != nil {
+		return nil, nil, mpcceremony.SignedArtifactRefs{}, err
+	}
+	refs := mpcceremony.SignedArtifactRefs{
+		Record:    mpcceremony.ArtifactRef{Name: options.AcknowledgementRecordName, Digest: mpcceremony.NewDigest(record)},
+		Signature: mpcceremony.ArtifactRef{Name: options.AcknowledgementSignatureName, Digest: mpcceremony.NewDigest(signature)},
+	}
+	if err := refs.Validate(); err != nil {
+		return nil, nil, mpcceremony.SignedArtifactRefs{}, err
+	}
+	return record, signature, refs, nil
+}
+
 func requireCheckpointArtifactName(ref mpcceremony.ArtifactRef, expected, label string) error {
 	if ref.Name != expected {
 		return fmt.Errorf("%s must use canonical storage path %q, got %q", label, expected, ref.Name)

cmd/mpc-ceremony/checkpoint_command_test.go

@@ -187,8 +187,8 @@ func TestCheckpointPrepareReceiptAcceptedAuthenticatesInnerEvidence(t *testing.T
 	if err != nil {
 		t.Fatal(err)
 	}
-	receiptPath := filepath.Join(fixture.root, "submissions", "receipt", slot.AttemptID, "receipt.json")
-	receiptSignaturePath := filepath.Join(fixture.root, "submissions", "receipt", slot.AttemptID, "receipt.sig")
+	receiptPath := filepath.Join(fixture.root, "phase1", "custody", "0001", "outbound-receipt.json")
+	receiptSignaturePath := filepath.Join(fixture.root, "phase1", "custody", "0001", "outbound-receipt.sig")
 	if err := os.MkdirAll(filepath.Dir(receiptPath), 0o700); err != nil {
 		t.Fatal(err)
 	}
@@ -221,6 +221,9 @@ func TestCheckpointPrepareReceiptAcceptedAuthenticatesInnerEvidence(t *testing.T
 	}
 	envelopePath := filepath.Join(fixture.root, "submissions", "receipt", slot.AttemptID, "envelope.json")
 	envelopeSignaturePath := filepath.Join(fixture.root, "submissions", "receipt", slot.AttemptID, "envelope.sig")
+	if err := os.MkdirAll(filepath.Dir(envelopePath), 0o700); err != nil {
+		t.Fatal(err)
+	}
 	envelopeBytes, envelopeSignatureBytes, err := mpcceremony.SignSubmissionEnvelope(fixture.definition, cp1, slot, envelope, participantKey)
 	if err != nil {
 		t.Fatal(err)
@@ -785,7 +788,7 @@ func prepareAndSignCandidateCheckpoint(t *testing.T, fixture checkpointCLIFixtur
 		ParentCheckpointSHA256: slot.BasisCheckpointSHA256, AllocationCheckpointSHA256: mpcceremony.NewDigest(previousBytes).SHA256,
 		ParentHeadID: slot.ParentHeadID, AttemptID: slot.AttemptID, ManifestKey: slot.ManifestKey, Payloads: payloads,
 	}
-	envelopeDir := filepath.Join(fixture.root, "submissions", string(phase)+"-candidate", slot.AttemptID)
+	envelopeDir := filepath.Join(fixture.root, filepath.FromSlash(strings.TrimSuffix(slot.ManifestKey, "/manifest.json")))
 	if err := os.MkdirAll(envelopeDir, 0o700); err != nil {
 		t.Fatal(err)
 	}
@@ -1037,11 +1040,11 @@ func prepareAndSignReceiptCheckpoint(t *testing.T, fixture checkpointCLIFixture,
 	if err != nil {
 		t.Fatal(err)
 	}
-	receiptDir := filepath.Join(fixture.root, "submissions", "receipt", slot.AttemptID)
+	receiptDir := filepath.Join(fixture.root, string(phase), "custody", fmt.Sprintf("%04d", slot.Index))
 	if err := os.MkdirAll(receiptDir, 0o700); err != nil {
 		t.Fatal(err)
 	}
-	receiptPath, receiptSignaturePath := filepath.Join(receiptDir, "receipt.json"), filepath.Join(receiptDir, "receipt.sig")
+	receiptPath, receiptSignaturePath := filepath.Join(receiptDir, "outbound-receipt.json"), filepath.Join(receiptDir, "outbound-receipt.sig")
 	receiptBytes, receiptSignatureBytes, err := mpcceremony.SignRecord(receipt, fixture.definition.Roster[0].Identity.KeyID, participantKey)
 	if err != nil {
 		t.Fatal(err)
@@ -1071,7 +1074,11 @@ func prepareAndSignReceiptCheckpoint(t *testing.T, fixture checkpointCLIFixture,
 		AttemptID:                  slot.AttemptID, ManifestKey: slot.ManifestKey,
 		Payloads: checkpointSortedArtifacts(receiptRef, receiptSignatureRef),
 	}
-	envelopePath, envelopeSignaturePath := filepath.Join(receiptDir, "envelope.json"), filepath.Join(receiptDir, "envelope.sig")
+	envelopeDir := filepath.Join(fixture.root, filepath.FromSlash(strings.TrimSuffix(slot.ManifestKey, "/manifest.json")))
+	if err := os.MkdirAll(envelopeDir, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	envelopePath, envelopeSignaturePath := filepath.Join(envelopeDir, "envelope.json"), filepath.Join(envelopeDir, "envelope.sig")
 	envelopeBytes, envelopeSignatureBytes, err := mpcceremony.SignSubmissionEnvelope(fixture.definition, cp1, slot, envelope, participantKey)
 	if err != nil {
 		t.Fatal(err)