add token type with permission checks and composable matchers
This commit is contained in:
juancwu
parent
5288df0b9e
commit
8b5fcc87c3
4 changed files with 499 additions and 0 deletions
92
matcher.go
Normal file
92
matcher.go
Normal file
|
|
@ -0,0 +1,92 @@
|
||||||
|
package ficha
|
||||||
|
|
||||||
|
// Matcher is a composable predicate evaluated against a Token.
|
||||||
|
// Use the package-level constructors All, Any, Not, Perm, and Check
|
||||||
|
// (on Token) to combine them.
|
||||||
|
type Matcher interface {
|
||||||
|
matches(t *Token) bool
|
||||||
|
}
|
||||||
|
|
||||||
|
// Perm returns a Matcher that checks for a single permission.
|
||||||
|
func Perm(p string) Matcher { return permMatcher(p) }
|
||||||
|
|
||||||
|
// All returns a Matcher that holds when every child matcher holds.
|
||||||
|
// Permission strings are accepted directly and treated as Perm(s).
|
||||||
|
// All() with no arguments holds (vacuous truth).
|
||||||
|
func All(matchers ...any) Matcher { return andMatcher(toMatchers(matchers)) }
|
||||||
|
|
||||||
|
// Any returns a Matcher that holds when at least one child matcher holds.
|
||||||
|
// Any() with no arguments does not hold.
|
||||||
|
func Any(matchers ...any) Matcher { return orMatcher(toMatchers(matchers)) }
|
||||||
|
|
||||||
|
// Not returns a Matcher that holds when the inner matcher does not.
|
||||||
|
// Strings are accepted and treated as Perm(s).
|
||||||
|
func Not(m any) Matcher {
|
||||||
|
return notMatcher{inner: toMatcher(m)}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Check evaluates a Matcher against the token.
|
||||||
|
func (t *Token) Check(m Matcher) bool {
|
||||||
|
if m == nil {
|
||||||
|
return false
|
||||||
|
}
|
||||||
|
return m.matches(t)
|
||||||
|
}
|
||||||
|
|
||||||
|
// --- internal matcher implementations ---
|
||||||
|
|
||||||
|
type permMatcher string
|
||||||
|
|
||||||
|
func (p permMatcher) matches(t *Token) bool { return t.Has(string(p)) }
|
||||||
|
|
||||||
|
type andMatcher []Matcher
|
||||||
|
|
||||||
|
func (a andMatcher) matches(t *Token) bool {
|
||||||
|
for _, m := range a {
|
||||||
|
if !m.matches(t) {
|
||||||
|
return false
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return true
|
||||||
|
}
|
||||||
|
|
||||||
|
type orMatcher []Matcher
|
||||||
|
|
||||||
|
func (o orMatcher) matches(t *Token) bool {
|
||||||
|
for _, m := range o {
|
||||||
|
if m.matches(t) {
|
||||||
|
return true
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return false
|
||||||
|
}
|
||||||
|
|
||||||
|
type notMatcher struct{ inner Matcher }
|
||||||
|
|
||||||
|
func (n notMatcher) matches(t *Token) bool { return !n.inner.matches(t) }
|
||||||
|
|
||||||
|
// toMatcher accepts either a string (treated as Perm) or a Matcher.
|
||||||
|
// Anything else produces a matcher that never holds — defensive but
|
||||||
|
// not panicking, since Matcher trees are often built dynamically.
|
||||||
|
func toMatcher(x any) Matcher {
|
||||||
|
switch v := x.(type) {
|
||||||
|
case string:
|
||||||
|
return permMatcher(v)
|
||||||
|
case Matcher:
|
||||||
|
return v
|
||||||
|
default:
|
||||||
|
return alwaysFalse{}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func toMatchers(xs []any) []Matcher {
|
||||||
|
out := make([]Matcher, len(xs))
|
||||||
|
for i, x := range xs {
|
||||||
|
out[i] = toMatcher(x)
|
||||||
|
}
|
||||||
|
return out
|
||||||
|
}
|
||||||
|
|
||||||
|
type alwaysFalse struct{}
|
||||||
|
|
||||||
|
func (alwaysFalse) matches(*Token) bool { return false }
|
||||||
91
matcher_test.go
Normal file
91
matcher_test.go
Normal file
|
|
@ -0,0 +1,91 @@
|
||||||
|
package ficha
|
||||||
|
|
||||||
|
import "testing"
|
||||||
|
|
||||||
|
func TestPermMatcher(t *testing.T) {
|
||||||
|
tok := makeToken("read", "write")
|
||||||
|
|
||||||
|
if !tok.Check(Perm("read")) {
|
||||||
|
t.Error("Perm(read) should match")
|
||||||
|
}
|
||||||
|
if tok.Check(Perm("delete")) {
|
||||||
|
t.Error("Perm(delete) should not match")
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestAllMatcher(t *testing.T) {
|
||||||
|
tok := makeToken("a", "b", "c")
|
||||||
|
|
||||||
|
if !tok.Check(All("a", "b")) {
|
||||||
|
t.Error("All(a,b) should match")
|
||||||
|
}
|
||||||
|
if tok.Check(All("a", "z")) {
|
||||||
|
t.Error("All(a,z) should not match")
|
||||||
|
}
|
||||||
|
if !tok.Check(All()) {
|
||||||
|
t.Error("All() empty should match (vacuous truth)")
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestAnyMatcher(t *testing.T) {
|
||||||
|
tok := makeToken("a")
|
||||||
|
|
||||||
|
if !tok.Check(Any("a", "z")) {
|
||||||
|
t.Error("Any(a,z) should match")
|
||||||
|
}
|
||||||
|
if tok.Check(Any("x", "y")) {
|
||||||
|
t.Error("Any(x,y) should not match")
|
||||||
|
}
|
||||||
|
if tok.Check(Any()) {
|
||||||
|
t.Error("Any() empty should not match")
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestNotMatcher(t *testing.T) {
|
||||||
|
tok := makeToken("a")
|
||||||
|
|
||||||
|
if !tok.Check(Not("z")) {
|
||||||
|
t.Error("Not(z) should match")
|
||||||
|
}
|
||||||
|
if tok.Check(Not("a")) {
|
||||||
|
t.Error("Not(a) should not match")
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestComposedMatchers(t *testing.T) {
|
||||||
|
tok := makeToken("orders:read", "billing-manager")
|
||||||
|
|
||||||
|
// (orders:read) AND (admin OR billing-manager) AND NOT readonly
|
||||||
|
m := All(
|
||||||
|
"orders:read",
|
||||||
|
Any("admin", "billing-manager"),
|
||||||
|
Not("readonly"),
|
||||||
|
)
|
||||||
|
if !tok.Check(m) {
|
||||||
|
t.Error("composed matcher should hold")
|
||||||
|
}
|
||||||
|
|
||||||
|
// Same with readonly added — Not should fail.
|
||||||
|
tokRO := makeToken("orders:read", "billing-manager", "readonly")
|
||||||
|
if tokRO.Check(m) {
|
||||||
|
t.Error("composed matcher should fail when readonly is present")
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestMatcherWithUnknownType(t *testing.T) {
|
||||||
|
tok := makeToken("a")
|
||||||
|
|
||||||
|
// Passing something that isn't a string or Matcher should
|
||||||
|
// produce a matcher that never holds — fail closed.
|
||||||
|
m := All(123, "a") // 123 is the bad input
|
||||||
|
if tok.Check(m) {
|
||||||
|
t.Error("matcher with unknown type should fail closed")
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestCheckNilMatcher(t *testing.T) {
|
||||||
|
tok := makeToken("a")
|
||||||
|
if tok.Check(nil) {
|
||||||
|
t.Error("Check(nil) should return false")
|
||||||
|
}
|
||||||
|
}
|
||||||
114
token.go
Normal file
114
token.go
Normal file
|
|
@ -0,0 +1,114 @@
|
||||||
|
package ficha
|
||||||
|
|
||||||
|
import (
|
||||||
|
"encoding/json"
|
||||||
|
"time"
|
||||||
|
)
|
||||||
|
|
||||||
|
// Token is a validated, decrypted token. It exposes the consumer-defined
|
||||||
|
// permissions and data, and provides methods for permission checks.
|
||||||
|
//
|
||||||
|
// Tokens are returned by Issuer.Validate. Consumers do not construct them
|
||||||
|
// directly. A Token is read-only — its methods do not mutate state.
|
||||||
|
type Token struct {
|
||||||
|
id string
|
||||||
|
issuedAt time.Time
|
||||||
|
expiresAt time.Time
|
||||||
|
permissions []string
|
||||||
|
data json.RawMessage
|
||||||
|
}
|
||||||
|
|
||||||
|
// newToken builds a Token from a decoded payload. Package-private —
|
||||||
|
// only the Issuer constructs Tokens, after successful validation.
|
||||||
|
func newToken(p payload) *Token {
|
||||||
|
return &Token{
|
||||||
|
id: p.ID,
|
||||||
|
issuedAt: time.Unix(p.Iat, 0),
|
||||||
|
expiresAt: time.Unix(p.Exp, 0),
|
||||||
|
permissions: p.Permissions,
|
||||||
|
data: p.Data,
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// ID returns the unique token identifier (used by the revocation store).
|
||||||
|
func (t *Token) ID() string { return t.id }
|
||||||
|
|
||||||
|
// IssuedAt returns when the token was issued.
|
||||||
|
func (t *Token) IssuedAt() time.Time { return t.issuedAt }
|
||||||
|
|
||||||
|
// ExpiresAt returns when the token expires.
|
||||||
|
func (t *Token) ExpiresAt() time.Time { return t.expiresAt }
|
||||||
|
|
||||||
|
// Permissions returns a copy of the token's permission strings.
|
||||||
|
// The returned slice is safe to retain and modify.
|
||||||
|
func (t *Token) Permissions() []string {
|
||||||
|
out := make([]string, len(t.permissions))
|
||||||
|
copy(out, t.permissions)
|
||||||
|
return out
|
||||||
|
}
|
||||||
|
|
||||||
|
// UnmarshalData decodes the consumer-defined data blob into v.
|
||||||
|
// Returns nil with v unchanged if the token has no data.
|
||||||
|
func (t *Token) UnmarshalData(v any) error {
|
||||||
|
if len(t.data) == 0 {
|
||||||
|
return nil
|
||||||
|
}
|
||||||
|
return json.Unmarshal(t.data, v)
|
||||||
|
}
|
||||||
|
|
||||||
|
// Has reports whether the token holds the given permission (exact match).
|
||||||
|
func (t *Token) Has(perm string) bool {
|
||||||
|
for _, p := range t.permissions {
|
||||||
|
if p == perm {
|
||||||
|
return true
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return false
|
||||||
|
}
|
||||||
|
|
||||||
|
// HasAll reports whether the token holds every given permission.
|
||||||
|
// Returns true when called with no arguments (vacuous truth). For a
|
||||||
|
// fail-closed variant that returns false on empty input, see RequiresAll.
|
||||||
|
func (t *Token) HasAll(perms ...string) bool {
|
||||||
|
for _, p := range perms {
|
||||||
|
if !t.Has(p) {
|
||||||
|
return false
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return true
|
||||||
|
}
|
||||||
|
|
||||||
|
// RequiresAll reports whether the token holds every given permission,
|
||||||
|
// and requires that at least one permission be specified. Returns false
|
||||||
|
// on empty input — use this when an empty permission list indicates a
|
||||||
|
// programmer error rather than a public/no-auth route.
|
||||||
|
//
|
||||||
|
// For the vacuous-truth variant (empty input → true), use HasAll.
|
||||||
|
func (t *Token) RequiresAll(perms ...string) bool {
|
||||||
|
if len(perms) == 0 {
|
||||||
|
return false
|
||||||
|
}
|
||||||
|
return t.HasAll(perms...)
|
||||||
|
}
|
||||||
|
|
||||||
|
// HasAny reports whether the token holds at least one of the given permissions.
|
||||||
|
// Returns false when called with no arguments.
|
||||||
|
func (t *Token) HasAny(perms ...string) bool {
|
||||||
|
for _, p := range perms {
|
||||||
|
if t.Has(p) {
|
||||||
|
return true
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return false
|
||||||
|
}
|
||||||
|
|
||||||
|
// HasNone reports whether the token holds none of the given permissions.
|
||||||
|
// Returns true when called with no arguments.
|
||||||
|
func (t *Token) HasNone(perms ...string) bool {
|
||||||
|
for _, p := range perms {
|
||||||
|
if t.Has(p) {
|
||||||
|
return false
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return true
|
||||||
|
}
|
||||||
202
token_test.go
Normal file
202
token_test.go
Normal file
|
|
@ -0,0 +1,202 @@
|
||||||
|
package ficha
|
||||||
|
|
||||||
|
import (
|
||||||
|
"encoding/json"
|
||||||
|
"testing"
|
||||||
|
"time"
|
||||||
|
)
|
||||||
|
|
||||||
|
func makeToken(perms ...string) *Token {
|
||||||
|
return &Token{
|
||||||
|
id: "tok_test",
|
||||||
|
issuedAt: time.Unix(1_700_000_000, 0),
|
||||||
|
expiresAt: time.Unix(1_700_003_600, 0),
|
||||||
|
permissions: perms,
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestTokenAccessors(t *testing.T) {
|
||||||
|
tok := makeToken("read", "write")
|
||||||
|
|
||||||
|
if tok.ID() != "tok_test" {
|
||||||
|
t.Errorf("ID: got %q", tok.ID())
|
||||||
|
}
|
||||||
|
if got := tok.IssuedAt().Unix(); got != 1_700_000_000 {
|
||||||
|
t.Errorf("IssuedAt: got %d", got)
|
||||||
|
}
|
||||||
|
if got := tok.ExpiresAt().Unix(); got != 1_700_003_600 {
|
||||||
|
t.Errorf("ExpiresAt: got %d", got)
|
||||||
|
}
|
||||||
|
|
||||||
|
perms := tok.Permissions()
|
||||||
|
if len(perms) != 2 || perms[0] != "read" || perms[1] != "write" {
|
||||||
|
t.Errorf("Permissions: got %v", perms)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestTokenPermissionsIsCopy(t *testing.T) {
|
||||||
|
tok := makeToken("read", "write")
|
||||||
|
perms := tok.Permissions()
|
||||||
|
perms[0] = "tampered"
|
||||||
|
|
||||||
|
if tok.Has("tampered") {
|
||||||
|
t.Error("mutating returned slice affected token state")
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestTokenHas(t *testing.T) {
|
||||||
|
tok := makeToken("read", "write", "admin")
|
||||||
|
|
||||||
|
cases := map[string]bool{
|
||||||
|
"read": true,
|
||||||
|
"write": true,
|
||||||
|
"admin": true,
|
||||||
|
"delete": false,
|
||||||
|
"": false,
|
||||||
|
}
|
||||||
|
for perm, want := range cases {
|
||||||
|
if got := tok.Has(perm); got != want {
|
||||||
|
t.Errorf("Has(%q): got %v, want %v", perm, got, want)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestTokenHasAll(t *testing.T) {
|
||||||
|
tok := makeToken("a", "b", "c")
|
||||||
|
|
||||||
|
tests := []struct {
|
||||||
|
name string
|
||||||
|
perms []string
|
||||||
|
want bool
|
||||||
|
}{
|
||||||
|
{"all present", []string{"a", "b"}, true},
|
||||||
|
{"all three", []string{"a", "b", "c"}, true},
|
||||||
|
{"one missing", []string{"a", "z"}, false},
|
||||||
|
{"none present", []string{"x", "y"}, false},
|
||||||
|
{"empty input is vacuously true", []string{}, true},
|
||||||
|
}
|
||||||
|
|
||||||
|
for _, tc := range tests {
|
||||||
|
t.Run(tc.name, func(t *testing.T) {
|
||||||
|
if got := tok.HasAll(tc.perms...); got != tc.want {
|
||||||
|
t.Errorf("got %v, want %v", got, tc.want)
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestTokenHasAny(t *testing.T) {
|
||||||
|
tok := makeToken("a", "b")
|
||||||
|
|
||||||
|
tests := []struct {
|
||||||
|
name string
|
||||||
|
perms []string
|
||||||
|
want bool
|
||||||
|
}{
|
||||||
|
{"one matches", []string{"a", "z"}, true},
|
||||||
|
{"all match", []string{"a", "b"}, true},
|
||||||
|
{"none match", []string{"x", "y"}, false},
|
||||||
|
{"empty input is false", []string{}, false},
|
||||||
|
}
|
||||||
|
|
||||||
|
for _, tc := range tests {
|
||||||
|
t.Run(tc.name, func(t *testing.T) {
|
||||||
|
if got := tok.HasAny(tc.perms...); got != tc.want {
|
||||||
|
t.Errorf("got %v, want %v", got, tc.want)
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestTokenHasNone(t *testing.T) {
|
||||||
|
tok := makeToken("a", "b")
|
||||||
|
|
||||||
|
tests := []struct {
|
||||||
|
name string
|
||||||
|
perms []string
|
||||||
|
want bool
|
||||||
|
}{
|
||||||
|
{"none of them present", []string{"x", "y"}, true},
|
||||||
|
{"one is present", []string{"a", "y"}, false},
|
||||||
|
{"empty input is vacuously true", []string{}, true},
|
||||||
|
}
|
||||||
|
|
||||||
|
for _, tc := range tests {
|
||||||
|
t.Run(tc.name, func(t *testing.T) {
|
||||||
|
if got := tok.HasNone(tc.perms...); got != tc.want {
|
||||||
|
t.Errorf("got %v, want %v", got, tc.want)
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestTokenUnmarshalData(t *testing.T) {
|
||||||
|
type meta struct {
|
||||||
|
UserID string `json:"user_id"`
|
||||||
|
Tier int `json:"tier"`
|
||||||
|
}
|
||||||
|
raw, _ := json.Marshal(meta{UserID: "u_42", Tier: 3})
|
||||||
|
|
||||||
|
tok := &Token{data: raw}
|
||||||
|
|
||||||
|
var got meta
|
||||||
|
if err := tok.UnmarshalData(&got); err != nil {
|
||||||
|
t.Fatalf("UnmarshalData: %v", err)
|
||||||
|
}
|
||||||
|
if got.UserID != "u_42" || got.Tier != 3 {
|
||||||
|
t.Errorf("got %+v", got)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestTokenUnmarshalDataEmpty(t *testing.T) {
|
||||||
|
tok := &Token{}
|
||||||
|
var got map[string]any
|
||||||
|
if err := tok.UnmarshalData(&got); err != nil {
|
||||||
|
t.Errorf("expected nil error on empty data, got %v", err)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestNewToken(t *testing.T) {
|
||||||
|
p := payload{
|
||||||
|
ID: "tok_x",
|
||||||
|
Iat: 1_700_000_000,
|
||||||
|
Exp: 1_700_003_600,
|
||||||
|
Permissions: []string{"read"},
|
||||||
|
Data: json.RawMessage(`{"x":1}`),
|
||||||
|
}
|
||||||
|
tok := newToken(p)
|
||||||
|
|
||||||
|
if tok.ID() != "tok_x" {
|
||||||
|
t.Errorf("ID: got %q", tok.ID())
|
||||||
|
}
|
||||||
|
if !tok.Has("read") {
|
||||||
|
t.Error("expected Has(read)")
|
||||||
|
}
|
||||||
|
if tok.IssuedAt().Unix() != 1_700_000_000 {
|
||||||
|
t.Errorf("IssuedAt: %v", tok.IssuedAt())
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestTokenRequiresAll(t *testing.T) {
|
||||||
|
tok := makeToken("a", "b", "c")
|
||||||
|
|
||||||
|
tests := []struct {
|
||||||
|
name string
|
||||||
|
perms []string
|
||||||
|
want bool
|
||||||
|
}{
|
||||||
|
{"all present", []string{"a", "b"}, true},
|
||||||
|
{"all three", []string{"a", "b", "c"}, true},
|
||||||
|
{"one missing", []string{"a", "z"}, false},
|
||||||
|
{"none present", []string{"x", "y"}, false},
|
||||||
|
{"empty input fails closed", []string{}, false},
|
||||||
|
}
|
||||||
|
|
||||||
|
for _, tc := range tests {
|
||||||
|
t.Run(tc.name, func(t *testing.T) {
|
||||||
|
if got := tok.RequiresAll(tc.perms...); got != tc.want {
|
||||||
|
t.Errorf("got %v, want %v", got, tc.want)
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
|
}
|
||||||
Loading…
Add table
Add a link
Reference in a new issue