refactor: make command.Command valid-by-construction (#21)

## Summary

`command.Command` was `type Command string`, so its validity invariant —
leading slash, lowercase, no trailing slash — was **not enforced by the
type**. Three ways to hold an invalid command existed:

1. **Conversion** — `command.Command("FOO/")` is legal Go.
2. **Zero value** — `var c command.Command` is `""`, which `Parse`
itself rejects.
3. **Unvalidated decode** — the generated wire path did a raw
`command.Command(sval)` with no check.

This PR models `Command` on the existing `did.DID` precedent: a struct
with an unexported field, obtainable only through validating
constructors. Invalid commands become unrepresentable.

## What changed

- **`Command` is now `struct{ str string }`** (was `type Command
string`). Added `MustParse`, `Undef`, and `Defined()`, mirroring
`did.DID`.
- **Serialization methods**
(`MarshalCBOR`/`UnmarshalCBOR`/`MarshalDagJSON`/`UnmarshalDagJSON`/`MarshalJSON`/`UnmarshalJSON`)
copied from `did.DID`. cbor-gen now **delegates** to them (the
`(struct)` codegen path), and **decode validates** — a non-conforming
command from the wire is rejected instead of silently accepted.
- **Wire format unchanged.** A command still serializes as the same CBOR
text string; fixtures and test vectors round-trip byte-identically
(`delegation`/`invocation`/`container`/`receipt` tests stay green).
- Regenerated the invocation/delegation datamodels.
- `receipt.Command`: `const` → `var command.MustParse(...)` (can't
`const` a struct).
- `invocation.go`/`delegation.go`: `string(command)` →
`command.String()` at the re-parse boundary.
- Updated call sites to build commands via `MustParse`. The "bad
command" test now feeds `command.Undef` — the only error path still
reachable now that invalid commands can't be constructed.
- Added `command_test.go` (the package previously had **no tests**):
parse table, `MustParse`, CBOR/DAG-JSON round-trips, and the
decode-validation guarantees.

## Notes

- `New(segments...)` still trusts its caller's segments (like
`cid`/`did` builders) rather than validating, to avoid a breaking
signature change rippling into `bindcom`. The headline guarantee comes
from the struct itself.
- Independent of the in-flight `binding` work; this also makes a future
`binding.Of(cmd command.Command)` a safe, error-free primitive.

Author: frrist

binding/handler_test.go

@@ -9,6 +9,7 @@ import (
 	"github.com/fil-forge/ucantone/ipld/datamodel"
 	"github.com/fil-forge/ucantone/testutil"
 	tdm "github.com/fil-forge/ucantone/testutil/datamodel"
+	"github.com/fil-forge/ucantone/ucan/command"
 	"github.com/fil-forge/ucantone/ucan/invocation"
 	"github.com/stretchr/testify/require"
 )
@@ -24,7 +25,7 @@ func TestHandler(t *testing.T) {
 	inv, err := invocation.Invoke(
 		alice,
 		alice.DID(),
-		"/test/handler",
+		command.MustParse("/test/handler"),
 		datamodel.Map{"bytes": []byte{0x01, 0x02, 0x03}},
 	)
 	require.NoError(t, err)

examples/container_test.go

@@ -6,6 +6,7 @@ import (
 
 	"github.com/fil-forge/ucantone/ipld/datamodel"
 	"github.com/fil-forge/ucantone/principal/ed25519"
+	"github.com/fil-forge/ucantone/ucan/command"
 	"github.com/fil-forge/ucantone/ucan/container"
 	"github.com/fil-forge/ucantone/ucan/delegation"
 	"github.com/fil-forge/ucantone/ucan/delegation/policy"
@@ -30,7 +31,7 @@ func TestContainer(t *testing.T) {
 		mailer,
 		alice.DID(),
 		mailer.DID(),
-		"/message/send",
+		command.MustParse("/message/send"),
 		delegation.WithPolicyBuilder(
 			policy.All(".to", policy.Like(".", "*.example.com")),
 		),
@@ -44,7 +45,7 @@ func TestContainer(t *testing.T) {
 	inv, err := invocation.Invoke(
 		alice,
 		mailer.DID(),
-		"/message/send",
+		command.MustParse("/message/send"),
 		datamodel.Map{
 			"to":      []string{"bob@example.com"},
 			"subject": "Hello!",

examples/delegations_test.go

@@ -4,6 +4,7 @@ import (
 	"testing"
 
 	"github.com/fil-forge/ucantone/principal/ed25519"
+	"github.com/fil-forge/ucantone/ucan/command"
 	"github.com/fil-forge/ucantone/ucan/delegation"
 	"github.com/fil-forge/ucantone/ucan/delegation/policy"
 )
@@ -27,10 +28,10 @@ func TestDelegations(t *testing.T) {
 
 	// delegate alice capability to use the email service
 	_, err = delegation.Delegate(
-		mailer,          // issuer
-		alice.DID(),     // audience (receiver)
-		mailer.DID(),    // subject
-		"/message/send", // command
+		mailer,                             // issuer
+		alice.DID(),                        // audience (receiver)
+		mailer.DID(),                       // subject
+		command.MustParse("/message/send"), // command
 	)
 	if err != nil {
 		panic(err)
@@ -40,7 +41,7 @@ func TestDelegations(t *testing.T) {
 		alice,
 		bob.DID(),
 		mailer.DID(),
-		"/message/send",
+		command.MustParse("/message/send"),
 		// alice delegates bob capability to use the email service, but only allows
 		// bob to send to example.com email addresses
 		delegation.WithPolicyBuilder(

examples/invocations_test.go

@@ -6,6 +6,7 @@ import (
 
 	"github.com/fil-forge/ucantone/ipld/datamodel"
 	"github.com/fil-forge/ucantone/principal/ed25519"
+	"github.com/fil-forge/ucantone/ucan/command"
 	"github.com/fil-forge/ucantone/ucan/delegation"
 	"github.com/fil-forge/ucantone/ucan/invocation"
 )
@@ -24,10 +25,10 @@ func TestInvocations(t *testing.T) {
 
 	// delegate alice capability to use the email service
 	dlg, err := delegation.Delegate(
-		mailer,          // issuer
-		alice.DID(),     // audience (receiver)
-		mailer.DID(),    // subject
-		"/message/send", // command
+		mailer,                             // issuer
+		alice.DID(),                        // audience (receiver)
+		mailer.DID(),                       // subject
+		command.MustParse("/message/send"), // command
 	)
 	if err != nil {
 		panic(err)
@@ -36,7 +37,7 @@ func TestInvocations(t *testing.T) {
 	inv, err := invocation.Invoke(
 		alice,
 		mailer.DID(),
-		"/message/send",
+		command.MustParse("/message/send"),
 		datamodel.Map{
 			"from":    "alice@example.com",
 			"to":      "bob@example.com",

examples/promises_test.go

@@ -7,6 +7,7 @@ import (
 	"github.com/fil-forge/ucantone/examples/types"
 	"github.com/fil-forge/ucantone/ipld/datamodel"
 	"github.com/fil-forge/ucantone/principal/ed25519"
+	"github.com/fil-forge/ucantone/ucan/command"
 	"github.com/fil-forge/ucantone/ucan/delegation"
 	"github.com/fil-forge/ucantone/ucan/invocation"
 	"github.com/fil-forge/ucantone/ucan/promise"
@@ -33,13 +34,13 @@ func TestPromises(t *testing.T) {
 	}
 
 	// A delegation from the mailer to alice allowing her to send emails
-	msgSendDlg, err := delegation.Delegate(mailer, alice.DID(), mailer.DID(), "/msg/send")
+	msgSendDlg, err := delegation.Delegate(mailer, alice.DID(), mailer.DID(), command.MustParse("/msg/send"))
 	if err != nil {
 		panic(err)
 	}
 
 	// A delegation from the mailing list to alice allowing her to read the emails
-	listEmailsDlg, err := delegation.Delegate(mailingList, alice.DID(), mailingList.DID(), "/emails/list")
+	listEmailsDlg, err := delegation.Delegate(mailingList, alice.DID(), mailingList.DID(), command.MustParse("/emails/list"))
 	if err != nil {
 		panic(err)
 	}
@@ -49,7 +50,7 @@ func TestPromises(t *testing.T) {
 	readListInv, err := invocation.Invoke(
 		alice,
 		mailingList.DID(),
-		"/emails/list",
+		command.MustParse("/emails/list"),
 		datamodel.Map{"limit": 100},
 		invocation.WithAudience(mailer.DID()),
 		invocation.WithProofs(listEmailsDlg.Link()),
@@ -64,7 +65,7 @@ func TestPromises(t *testing.T) {
 	msgSendInv, err := invocation.Invoke(
 		alice,
 		mailer.DID(),
-		"/msg/send",
+		command.MustParse("/msg/send"),
 		datamodel.Map{
 			"from":    "alice@example.com",
 			"to":      datamodel.Map{"await/ok": readListInv.Task().Link()},

examples/typed_args_test.go

@@ -11,6 +11,7 @@ import (
 	"github.com/fil-forge/ucantone/examples/types"
 	"github.com/fil-forge/ucantone/ipld/datamodel"
 	"github.com/fil-forge/ucantone/principal/ed25519"
+	"github.com/fil-forge/ucantone/ucan/command"
 	"github.com/fil-forge/ucantone/ucan/invocation"
 	"github.com/fil-forge/ucantone/ucan/receipt"
 )
@@ -44,7 +45,7 @@ func TestExtractTypedArgsFromInvocation(t *testing.T) {
 	inv, err := invocation.Invoke(
 		alice,
 		alice.DID(), // subject
-		"/example/echo",
+		command.MustParse("/example/echo"),
 		&types.EchoArguments{Message: "Hello, UCAN!"},
 		invocation.WithMetadata(map[string]any{
 			"trace_id":   "abc-123",

ucan/command/command.go

@@ -1,8 +1,13 @@
 package command
 
 import (
+	"bytes"
 	"fmt"
+	"io"
 	"strings"
+
+	jsg "github.com/alanshaw/dag-json-gen"
+	cbg "github.com/whyrusleeping/cbor-gen"
 )
 
 const separator = "/"
@@ -13,11 +18,33 @@ const separator = "/"
 // A [Command] is composed of a leading slash which is optionally followed by
 // one or more slash-separated Segments of lowercase characters.
 //
+// The underlying field is unexported so a Command can only be obtained from a
+// validating constructor ([New], [Parse], [MustParse] or [Top]). This makes
+// invalid Commands unrepresentable: a value of this type is always either the
+// undefined zero value or a well-formed command.
+//
+// Note: this is a struct rather than `type Command string` for two reasons —
+// it prevents arbitrary strings being converted into a Command, and cbor-gen
+// only recognises MarshalCBOR/UnmarshalCBOR on non-string (struct) types.
+//
 // [Command]: https://github.com/ucan-wg/spec#command
-type Command string
+type Command struct {
+	str string
+}
+
+// Undef is the zero value of Command, representing an undefined command. Using
+// Command{} directly is also acceptable.
+var Undef = Command{}
 
-// New creates a validated command from the provided list of segment strings. An
-// error is returned if an invalid Command would be formed
+// Defined reports whether the Command holds a value (i.e. is not the undefined
+// zero value).
+func (c Command) Defined() bool {
+	return c.str != ""
+}
+
+// New creates a command from the provided segments. Segments are assumed to be
+// well-formed; New does not validate them. To validate untrusted input, use
+// [Parse].
 func New(segments ...string) Command {
 	return Top().Join(segments...)
 }
@@ -28,20 +55,30 @@ func New(segments ...string) Command {
 // [segment structure]: https://github.com/ucan-wg/spec#segment-structure
 func Parse(s string) (Command, error) {
 	if !strings.HasPrefix(s, "/") {
-		return "", ErrRequiresLeadingSlash
+		return Undef, ErrRequiresLeadingSlash
 	}
 
 	if len(s) > 1 && strings.HasSuffix(s, "/") {
-		return "", ErrDisallowsTrailingSlash
+		return Undef, ErrDisallowsTrailingSlash
 	}
 
 	if s != strings.ToLower(s) {
-		return "", ErrRequiresLowercase
+		return Undef, ErrRequiresLowercase
 	}
 
-	// The leading slash will result in the first element from strings. Split
+	// The leading slash will result in the first element from strings.Split
 	// being an empty string which is removed as strings.Join will ignore it.
-	return Command(s), nil
+	return Command{str: s}, nil
+}
+
+// MustParse is like [Parse] but panics if s is not a valid Command. It is
+// intended for package-level command definitions from constant strings.
+func MustParse(s string) Command {
+	cmd, err := Parse(s)
+	if err != nil {
+		panic(fmt.Sprintf("command: MustParse(%q): %v", s, err))
+	}
+	return cmd
 }
 
 // Top is the most powerful capability.
@@ -52,7 +89,7 @@ func Parse(s string) (Command, error) {
 //
 // [Top]: https://github.com/ucan-wg/spec#-aka-top
 func Top() Command {
-	return Command(separator)
+	return Command{str: separator}
 }
 
 // Join appends segments to the end of this command using the required
@@ -65,8 +102,8 @@ func (c Command) Join(segments ...string) Command {
 	if size == 0 {
 		return c
 	}
-	buf := make([]byte, 0, len(c)+size+len(segments))
-	buf = append(buf, []byte(c)...)
+	buf := make([]byte, 0, len(c.str)+size+len(segments))
+	buf = append(buf, []byte(c.str)...)
 	for _, s := range segments {
 		if s != "" {
 			if len(buf) > 1 {
@@ -75,16 +112,16 @@ func (c Command) Join(segments ...string) Command {
 			buf = append(buf, []byte(s)...)
 		}
 	}
-	return Command(buf)
+	return Command{str: string(buf)}
 }
 
 // Segments returns the ordered segments that comprise the Command as a slice
 // of strings.
 func (c Command) Segments() []string {
-	if c == separator {
+	if c.str == separator {
 		return nil
 	}
-	return strings.Split(string(c), separator)[1:]
+	return strings.Split(c.str, separator)[1:]
 }
 
 // Proves returns true if the command is identical or a parent of the given
@@ -96,16 +133,93 @@ func (c Command) Segments() []string {
 // https://github.com/ucan-wg/spec/blob/main/README.md#segment-structure
 func (c Command) Proves(other Command) bool {
 	// fast-path, equivalent to the code below (verified with fuzzing)
-	if !strings.HasPrefix(string(other), string(c)) {
+	if !strings.HasPrefix(other.str, c.str) {
 		return false
 	}
-	return c == separator || len(c) == len(other) || other[len(c)] == separator[0]
+	return c.str == separator || len(c.str) == len(other.str) || other.str[len(c.str)] == separator[0]
 }
 
 // String returns the composed representation the command. This is also the
 // required wire representation (before IPLD encoding occurs).
 func (c Command) String() string {
-	return string(c)
+	return c.str
+}
+
+func (c Command) MarshalJSON() ([]byte, error) {
+	var buf bytes.Buffer
+	if err := c.MarshalDagJSON(&buf); err != nil {
+		return nil, err
+	}
+	return buf.Bytes(), nil
+}
+
+func (c *Command) UnmarshalJSON(b []byte) error {
+	return c.UnmarshalDagJSON(bytes.NewReader(b))
+}
+
+func (c Command) MarshalCBOR(w io.Writer) error {
+	if c.str == "" {
+		_, err := w.Write(cbg.CborNull)
+		return err
+	}
+	cw := cbg.NewCborWriter(w)
+	if err := cw.WriteMajorTypeHeader(cbg.MajTextString, uint64(len(c.str))); err != nil {
+		return err
+	}
+	_, err := cw.WriteString(c.str)
+	return err
+}
+
+func (c *Command) UnmarshalCBOR(r io.Reader) error {
+	cr := cbg.NewCborReader(r)
+	b, err := cr.ReadByte()
+	if err != nil {
+		return err
+	}
+	if b != cbg.CborNull[0] {
+		if err := cr.UnreadByte(); err != nil {
+			return err
+		}
+		str, err := cbg.ReadStringWithMax(cr, 2048)
+		if err != nil {
+			return err
+		}
+		parsed, err := Parse(str)
+		if err != nil {
+			return err
+		}
+		*c = parsed
+	}
+	return nil
+}
+
+func (c Command) MarshalDagJSON(w io.Writer) error {
+	jw := jsg.NewDagJsonWriter(w)
+	if c.str == "" {
+		return jw.WriteNull()
+	}
+	return jw.WriteString(c.str)
 }
 
-var _ fmt.Stringer = (*Command)(nil)
+func (c *Command) UnmarshalDagJSON(r io.Reader) error {
+	jr := jsg.NewDagJsonReader(r)
+	str, err := jr.ReadStringOrNull(jsg.MaxLength)
+	if err != nil {
+		return err
+	}
+	if str == nil {
+		return nil
+	}
+	parsed, err := Parse(*str)
+	if err != nil {
+		return err
+	}
+	*c = parsed
+	return nil
+}
+
+var (
+	_ fmt.Stringer        = (*Command)(nil)
+	_ cbg.CBORMarshaler   = (*Command)(nil)
+	_ cbg.CBORUnmarshaler = (*Command)(nil)
+)