Merge pull request #109 from wpaulino/lsat-basics

lsat: introduce LSAT related utilities

Author: Roasbeef

lsat/caveat.go

@@ -0,0 +1,142 @@
+package lsat
+
+import (
+	"errors"
+	"fmt"
+	"strings"
+
+	"gopkg.in/macaroon.v2"
+)
+
+const (
+	// PreimageKey is the key used for a payment preimage caveat.
+	PreimageKey = "preimage"
+)
+
+var (
+	// ErrInvalidCaveat is an error returned when we attempt to decode a
+	// caveat with an invalid format.
+	ErrInvalidCaveat = errors.New("caveat must be of the form " +
+		"\"condition=value\"")
+)
+
+// Caveat is a predicate that can be applied to an LSAT in order to restrict its
+// use in some form. Caveats are evaluated during LSAT verification after the
+// LSAT's signature is verified. The predicate of each caveat must hold true in
+// order to successfully validate an LSAT.
+type Caveat struct {
+	// Condition serves as a way to identify a caveat and how to satisfy it.
+	Condition string
+
+	// Value is what will be used to satisfy a caveat. This can be as
+	// flexible as needed, as long as it can be encoded into a string.
+	Value string
+}
+
+// NewCaveat construct a new caveat with the given condition and value.
+func NewCaveat(condition string, value string) Caveat {
+	return Caveat{Condition: condition, Value: value}
+}
+
+// String returns a user-friendly view of a caveat.
+func (c Caveat) String() string {
+	return EncodeCaveat(c)
+}
+
+// EncodeCaveat encodes a caveat into its string representation.
+func EncodeCaveat(c Caveat) string {
+	return fmt.Sprintf("%v=%v", c.Condition, c.Value)
+}
+
+// DecodeCaveat decodes a caveat from its string representation.
+func DecodeCaveat(s string) (Caveat, error) {
+	parts := strings.SplitN(s, "=", 2)
+	if len(parts) != 2 {
+		return Caveat{}, ErrInvalidCaveat
+	}
+	return Caveat{Condition: parts[0], Value: parts[1]}, nil
+}
+
+// AddFirstPartyCaveats adds a set of caveats as first-party caveats to a
+// macaroon.
+func AddFirstPartyCaveats(m *macaroon.Macaroon, caveats ...Caveat) error {
+	for _, c := range caveats {
+		rawCaveat := []byte(EncodeCaveat(c))
+		if err := m.AddFirstPartyCaveat(rawCaveat); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+// HasCaveat checks whether the given macaroon has a caveat with the given
+// condition, and if so, returns its value. If multiple caveats with the same
+// condition exist, then the value of the last one is returned.
+func HasCaveat(m *macaroon.Macaroon, cond string) (string, bool) {
+	var value *string
+	for _, rawCaveat := range m.Caveats() {
+		caveat, err := DecodeCaveat(string(rawCaveat.Id))
+		if err != nil {
+			// Ignore any unknown caveats as we can't decode them.
+			continue
+		}
+		if caveat.Condition == cond {
+			value = &caveat.Value
+		}
+	}
+
+	if value == nil {
+		return "", false
+	}
+	return *value, true
+}
+
+// VerifyCaveats determines whether every relevant caveat of an LSAT holds true.
+// A caveat is considered relevant if a satisfier is provided for it, which is
+// what we'll use as their evaluation.
+//
+// NOTE: The caveats provided should be in the same order as in the LSAT to
+// ensure the correctness of each satisfier's SatisfyPrevious.
+func VerifyCaveats(caveats []Caveat, satisfiers ...Satisfier) error {
+	// Construct a set of our satisfiers to determine which caveats we know
+	// how to satisfy.
+	caveatSatisfiers := make(map[string]Satisfier, len(satisfiers))
+	for _, satisfier := range satisfiers {
+		caveatSatisfiers[satisfier.Condition] = satisfier
+	}
+	relevantCaveats := make(map[string][]Caveat)
+	for _, caveat := range caveats {
+		if _, ok := caveatSatisfiers[caveat.Condition]; !ok {
+			continue
+		}
+		relevantCaveats[caveat.Condition] = append(
+			relevantCaveats[caveat.Condition], caveat,
+		)
+	}
+
+	for condition, caveats := range relevantCaveats {
+		satisfier := caveatSatisfiers[condition]
+
+		// Since it's possible for a chain of caveat to exist for the
+		// same condition as a way to demote privileges, we'll ensure
+		// each one satisfies its previous.
+		for i, j := 0, 1; j < len(caveats); i, j = i+1, j+1 {
+			prevCaveat := caveats[i]
+			curCaveat := caveats[j]
+			err := satisfier.SatisfyPrevious(prevCaveat, curCaveat)
+			if err != nil {
+				return err
+			}
+		}
+
+		// Once we verify the previous ones, if any, we can proceed to
+		// verify the final one, which is the decision maker.
+		err := satisfier.SatisfyFinal(caveats[len(caveats)-1])
+		if err != nil {
+			return err
+		}
+	}
+
+	return nil
+}

lsat/caveat_test.go

@@ -0,0 +1,202 @@
+package lsat
+
+import (
+	"errors"
+	"testing"
+
+	"gopkg.in/macaroon.v2"
+)
+
+var (
+	testMacaroon, _ = macaroon.New(nil, nil, "", macaroon.LatestVersion)
+)
+
+// TestCaveatSerialization ensures that we can properly encode/decode valid
+// caveats and cannot do so for invalid ones.
+func TestCaveatSerialization(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name      string
+		caveatStr string
+		err       error
+	}{
+		{
+			name:      "valid caveat",
+			caveatStr: "expiration=1337",
+			err:       nil,
+		},
+		{
+			name:      "valid caveat with separator in value",
+			caveatStr: "expiration=1337=",
+			err:       nil,
+		},
+		{
+			name:      "invalid caveat",
+			caveatStr: "expiration:1337",
+			err:       ErrInvalidCaveat,
+		},
+	}
+
+	for _, test := range tests {
+		test := test
+		success := t.Run(test.name, func(t *testing.T) {
+			caveat, err := DecodeCaveat(test.caveatStr)
+			if !errors.Is(err, test.err) {
+				t.Fatalf("expected err \"%v\", got \"%v\"",
+					test.err, err)
+			}
+
+			if test.err != nil {
+				return
+			}
+
+			caveatStr := EncodeCaveat(caveat)
+			if caveatStr != test.caveatStr {
+				t.Fatalf("expected encoded caveat \"%v\", "+
+					"got \"%v\"", test.caveatStr, caveatStr)
+			}
+		})
+		if !success {
+			return
+		}
+	}
+}
+
+// TestHasCaveat ensures we can determine whether a macaroon contains a caveat
+// with a specific condition.
+func TestHasCaveat(t *testing.T) {
+	t.Parallel()
+
+	const (
+		cond  = "cond"
+		value = "value"
+	)
+	m := testMacaroon.Clone()
+
+	// The macaroon doesn't have any caveats, so we shouldn't find any.
+	if _, ok := HasCaveat(m, cond); ok {
+		t.Fatal("found unexpected caveat with unknown condition")
+	}
+
+	// Add two caveats, one in a valid LSAT format and another invalid.
+	// We'll test that we're still able to determine the macaroon contains
+	// the valid caveat even though there is one that is invalid.
+	invalidCaveat := []byte("invalid")
+	if err := m.AddFirstPartyCaveat(invalidCaveat); err != nil {
+		t.Fatalf("unable to add macaroon caveat: %v", err)
+	}
+	validCaveat1 := Caveat{Condition: cond, Value: value}
+	if err := AddFirstPartyCaveats(m, validCaveat1); err != nil {
+		t.Fatalf("unable to add macaroon caveat: %v", err)
+	}
+
+	caveatValue, ok := HasCaveat(m, cond)
+	if !ok {
+		t.Fatal("expected macaroon to contain caveat")
+	}
+	if caveatValue != validCaveat1.Value {
+		t.Fatalf("expected caveat value \"%v\", got \"%v\"",
+			validCaveat1.Value, caveatValue)
+	}
+
+	// If we add another caveat with the same condition, the value of the
+	// most recently added caveat should be returned instead.
+	validCaveat2 := validCaveat1
+	validCaveat2.Value += value
+	if err := AddFirstPartyCaveats(m, validCaveat2); err != nil {
+		t.Fatalf("unable to add macaroon caveat: %v", err)
+	}
+
+	caveatValue, ok = HasCaveat(m, cond)
+	if !ok {
+		t.Fatal("expected macaroon to contain caveat")
+	}
+	if caveatValue != validCaveat2.Value {
+		t.Fatalf("expected caveat value \"%v\", got \"%v\"",
+			validCaveat2.Value, caveatValue)
+	}
+}
+
+// TestVerifyCaveats ensures caveat verification only holds true for known
+// caveats.
+func TestVerifyCaveats(t *testing.T) {
+	t.Parallel()
+
+	caveat1 := Caveat{Condition: "1", Value: "test"}
+	caveat2 := Caveat{Condition: "2", Value: "test"}
+	satisfier := Satisfier{
+		Condition: caveat1.Condition,
+		SatisfyPrevious: func(c Caveat, prev Caveat) error {
+			return nil
+		},
+		SatisfyFinal: func(c Caveat) error {
+			return nil
+		},
+	}
+	invalidSatisfyPrevious := func(c Caveat, prev Caveat) error {
+		return errors.New("no")
+	}
+	invalidSatisfyFinal := func(c Caveat) error {
+		return errors.New("no")
+	}
+
+	tests := []struct {
+		name       string
+		caveats    []Caveat
+		satisfiers []Satisfier
+		shouldFail bool
+	}{
+		{
+			name:       "simple verification",
+			caveats:    []Caveat{caveat1},
+			satisfiers: []Satisfier{satisfier},
+			shouldFail: false,
+		},
+		{
+			name:       "unknown caveat",
+			caveats:    []Caveat{caveat1, caveat2},
+			satisfiers: []Satisfier{satisfier},
+			shouldFail: false,
+		},
+		{
+			name:    "one invalid",
+			caveats: []Caveat{caveat1, caveat2},
+			satisfiers: []Satisfier{
+				satisfier,
+				{
+					Condition:    caveat2.Condition,
+					SatisfyFinal: invalidSatisfyFinal,
+				},
+			},
+			shouldFail: true,
+		},
+		{
+			name:    "prev invalid",
+			caveats: []Caveat{caveat1, caveat1},
+			satisfiers: []Satisfier{
+				{
+					Condition:       caveat1.Condition,
+					SatisfyPrevious: invalidSatisfyPrevious,
+				},
+			},
+			shouldFail: true,
+		},
+	}
+
+	for _, test := range tests {
+		test := test
+		success := t.Run(test.name, func(t *testing.T) {
+			err := VerifyCaveats(test.caveats, test.satisfiers...)
+			if test.shouldFail && err == nil {
+				t.Fatal("expected caveat verification to fail")
+			}
+			if !test.shouldFail && err != nil {
+				t.Fatal("unexpected caveat verification failure")
+			}
+		})
+		if !success {
+			return
+		}
+	}
+}