Skip to content

Agent Mesh

identity: bind a token to its peer via the authority block only

Antonio Ojead0023dd669f2
diff --git a/internal/identity/biscuit.go b/internal/identity/biscuit.go
index 71c851e2..5049c506 100644
--- a/internal/identity/biscuit.go
+++ b/internal/identity/biscuit.go
@@ -62,6 +62,35 @@ func EnforceExpiration(authorizer biscuit.Authorizer) {
authorizer.AddCheck(api.ControlPlaneStaticTimeCheck)
}
+// authorityBlockID is the block index biscuit-go reports for a fact carried by
+// the root-signed authority block. Every other index is an appended attenuation
+// block, which any token holder can create without the root key.
+const authorityBlockID = 0
+
+// RequireAuthorityBinding checks that the token is bound to expectedPeer by an
+// api.FactNode fact in the authority block.
+//
+// The block matters. biscuit-go's GetBlockID searches appended attenuation
+// blocks too, and appending needs no root key, so a holder of anyone's token can
+// append node(<their own peer id>) offline and satisfy a binding that only tests
+// the error. Those facts are invisible to the Datalog authorizer (see
+// TestAttenuationBlockFactsAreInvisibleToTheAuthorizer), so this lookup is the
+// only place the distinction has to be made by hand.
+func RequireAuthorityBinding(b *biscuit.Biscuit, expectedPeer peer.ID) error {
+ boundFact := biscuit.Fact{Predicate: biscuit.Predicate{
+ Name: api.FactNode,
+ IDs: []biscuit.Term{biscuit.String(expectedPeer.String())},
+ }}
+ blockID, err := b.GetBlockID(boundFact)
+ if err != nil {
+ return fmt.Errorf("token is not bound to peer %s: %w", expectedPeer, err)
+ }
+ if blockID != authorityBlockID {
+ return fmt.Errorf("token is not bound to peer %s: %s fact comes from appended block %d, not the authority block", expectedPeer, api.FactNode, blockID)
+ }
+ return nil
+}
+
// ExpirationOf reports the expiration() fact of an already-authorized token, for
// callers that cache an admission decision and must later know when it lapses.
func ExpirationOf(authorizer biscuit.Authorizer) (time.Time, error) {
@@ -315,13 +344,8 @@ func VerifyBiscuitAndGetKey(biscuitData []byte, expectedPeer peer.ID, trustedPub
return nil, nil, fmt.Errorf("no valid key found for verification: %v", lastErr)
}
- // Enforce hardware binding
- boundFact := biscuit.Fact{Predicate: biscuit.Predicate{
- Name: "node",
- IDs: []biscuit.Term{biscuit.String(expectedPeer.String())},
- }}
- if _, err := b.GetBlockID(boundFact); err != nil {
- return nil, nil, fmt.Errorf("token is not bound to peer %s: %w", expectedPeer, err)
+ if err := RequireAuthorityBinding(b, expectedPeer); err != nil {
+ return nil, nil, err
}
return b, verifyingKey, nil
diff --git a/internal/identity/peer_binding_test.go b/internal/identity/peer_binding_test.go
new file mode 100644
index 00000000..f4afc7e8
--- /dev/null
+++ b/internal/identity/peer_binding_test.go
@@ -0,0 +1,148 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package identity
+
+import (
+ "crypto/ed25519"
+ "crypto/rand"
+ "testing"
+ "time"
+
+ "github.com/biscuit-auth/biscuit-go/v2"
+ "github.com/google/sam/api"
+ "github.com/libp2p/go-libp2p/core/crypto"
+ "github.com/libp2p/go-libp2p/core/peer"
+)
+
+// TestGetBlockIDIndexesTheAuthorityBlockAsZero pins the library behaviour that
+// RequireAuthorityBinding rests on. If biscuit-go ever renumbers blocks, the
+// binding check silently starts accepting appended facts again, so this has to
+// fail loudly rather than be re-derived from the docs.
+func TestGetBlockIDIndexesTheAuthorityBlockAsZero(t *testing.T) {
+ _, priv, err := ed25519.GenerateKey(rand.Reader)
+ if err != nil {
+ t.Fatalf("GenerateKey: %v", err)
+ }
+
+ authorityFact := biscuit.Fact{Predicate: biscuit.Predicate{
+ Name: api.FactNode,
+ IDs: []biscuit.Term{biscuit.String("authority")},
+ }}
+ appendedFact := biscuit.Fact{Predicate: biscuit.Predicate{
+ Name: api.FactNode,
+ IDs: []biscuit.Term{biscuit.String("appended")},
+ }}
+
+ builder := biscuit.NewBuilder(priv)
+ if err := builder.AddAuthorityFact(authorityFact); err != nil {
+ t.Fatalf("AddAuthorityFact: %v", err)
+ }
+ token, err := builder.Build()
+ if err != nil {
+ t.Fatalf("Build: %v", err)
+ }
+
+ block := token.CreateBlock()
+ if err := block.AddFact(appendedFact); err != nil {
+ t.Fatalf("AddFact: %v", err)
+ }
+ attenuated, err := token.Append(rand.Reader, block.Build())
+ if err != nil {
+ t.Fatalf("Append: %v", err)
+ }
+
+ if id, err := attenuated.GetBlockID(authorityFact); err != nil || id != authorityBlockID {
+ t.Errorf("authority fact reported block %d (err %v), want %d", id, err, authorityBlockID)
+ }
+ if id, err := attenuated.GetBlockID(appendedFact); err != nil || id == authorityBlockID {
+ t.Errorf("appended fact reported block %d (err %v), want a non-authority block", id, err)
+ }
+}
+
+// TestPeerBindingRejectsAppendedBlock is the regression test for the binding
+// bypass: appending a block needs no root key, so a holder of *any* valid token
+// could append node(<their own peer id>) and pass a binding check that only
+// looked at GetBlockID's error. The signature chain still verifies and the
+// authority facts are untouched, which is exactly what made it dangerous.
+func TestPeerBindingRejectsAppendedBlock(t *testing.T) {
+ pub, priv, err := ed25519.GenerateKey(rand.Reader)
+ if err != nil {
+ t.Fatalf("GenerateKey: %v", err)
+ }
+ victim := newTestPeer(t)
+ attacker := newTestPeer(t)
+
+ builder := biscuit.NewBuilder(priv)
+ for _, f := range []biscuit.Fact{
+ {Predicate: biscuit.Predicate{Name: api.FactNode, IDs: []biscuit.Term{biscuit.String(victim.String())}}},
+ {Predicate: biscuit.Predicate{Name: api.FactRole, IDs: []biscuit.Term{biscuit.String(api.RoleRouter)}}},
+ {Predicate: biscuit.Predicate{Name: api.FactExpiration, IDs: []biscuit.Term{biscuit.Date(time.Now().Add(time.Hour))}}},
+ } {
+ if err := builder.AddAuthorityFact(f); err != nil {
+ t.Fatalf("AddAuthorityFact: %v", err)
+ }
+ }
+ token, err := builder.Build()
+ if err != nil {
+ t.Fatalf("Build: %v", err)
+ }
+
+ block := token.CreateBlock()
+ if err := block.AddFact(biscuit.Fact{Predicate: biscuit.Predicate{
+ Name: api.FactNode,
+ IDs: []biscuit.Term{biscuit.String(attacker.String())},
+ }}); err != nil {
+ t.Fatalf("AddFact: %v", err)
+ }
+ attenuated, err := token.Append(rand.Reader, block.Build())
+ if err != nil {
+ t.Fatalf("Append: %v", err)
+ }
+ forged, err := attenuated.Serialize()
+ if err != nil {
+ t.Fatalf("Serialize: %v", err)
+ }
+
+ keys := []ed25519.PublicKey{pub}
+
+ if err := RequireAuthorityBinding(attenuated, attacker); err == nil {
+ t.Error("RequireAuthorityBinding accepted a peer bound only by an appended block")
+ }
+ if err := RequireAuthorityBinding(attenuated, victim); err != nil {
+ t.Errorf("RequireAuthorityBinding rejected the token's real owner: %v", err)
+ }
+
+ if _, err := VerifyBiscuit(forged, attacker, keys, time.Second); err == nil {
+ t.Error("VerifyBiscuit admitted a token re-bound by an appended block")
+ }
+ // Attenuation must stay usable for the peer the authority block names,
+ // otherwise this fix would break delegation instead of the bypass.
+ if _, err := VerifyBiscuit(forged, victim, keys, time.Second); err != nil {
+ t.Errorf("VerifyBiscuit rejected an attenuated token held by its real owner: %v", err)
+ }
+}
+
+func newTestPeer(t *testing.T) peer.ID {
+ t.Helper()
+ priv, _, err := crypto.GenerateKeyPair(crypto.Ed25519, -1)
+ if err != nil {
+ t.Fatalf("GenerateKeyPair: %v", err)
+ }
+ id, err := peer.IDFromPrivateKey(priv)
+ if err != nil {
+ t.Fatalf("IDFromPrivateKey: %v", err)
+ }
+ return id
+}
diff --git a/internal/node/middleware.go b/internal/node/middleware.go
index 538ea485..a94c0cb8 100644
--- a/internal/node/middleware.go
+++ b/internal/node/middleware.go
@@ -213,13 +213,8 @@ func (n *SamNode) Authorize(rawToken []byte, req RequestContext, pubKey ed25519.
return err
}
- // Verify that the token is bound to the connecting peer's ID
- boundFact := biscuit.Fact{Predicate: biscuit.Predicate{
- Name: "node",
- IDs: []biscuit.Term{biscuit.String(req.PeerID.String())},
- }}
- if _, err := b.GetBlockID(boundFact); err != nil {
- return fmt.Errorf("token is not bound to peer %s", req.PeerID)
+ if err := identity.RequireAuthorityBinding(b, req.PeerID); err != nil {
+ return err
}
// Inject the current action context (Standard Vocabulary)
diff --git a/internal/node/middleware_test.go b/internal/node/middleware_test.go
index 7befbed1..ed9c4312 100644
--- a/internal/node/middleware_test.go
+++ b/internal/node/middleware_test.go
@@ -18,6 +18,7 @@ import (
"bytes"
"context"
"crypto/ed25519"
+ cryptorand "crypto/rand"
"fmt"
"io"
@@ -248,6 +249,64 @@ func TestAuthorizeRejectsExpiredBiscuit(t *testing.T) {
}
}
+// TestAuthorizeRejectsAppendedPeerBinding covers the dataplane half of the
+// binding bypass. Appending a block needs no root key, so a peer holding any
+// valid token could append node(<its own peer id>) and connect under its own
+// libp2p key; the binding must only honour the authority block.
+func TestAuthorizeRejectsAppendedPeerBinding(t *testing.T) {
+ pub, priv, err := ed25519.GenerateKey(nil)
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ victim := peer.ID("victim-peer")
+ attacker := peer.ID("attacker-peer")
+
+ builder := biscuit.NewBuilder(priv)
+ for _, f := range []biscuit.Fact{
+ {Predicate: biscuit.Predicate{Name: api.FactTargetUnrestricted}},
+ {Predicate: biscuit.Predicate{Name: api.FactNode, IDs: []biscuit.Term{biscuit.String(victim.String())}}},
+ {Predicate: biscuit.Predicate{Name: api.FactClientPeerID, IDs: []biscuit.Term{biscuit.String(attacker.String())}}},
+ {Predicate: biscuit.Predicate{Name: api.FactGrantedServiceExact, IDs: []biscuit.Term{biscuit.String(api.SystemNamespace), biscuit.String("/test/proto")}}},
+ {Predicate: biscuit.Predicate{Name: api.FactExpiration, IDs: []biscuit.Term{biscuit.Date(time.Now().Add(time.Hour))}}},
+ } {
+ if err := builder.AddAuthorityFact(f); err != nil {
+ t.Fatal(err)
+ }
+ }
+
+ b, err := builder.Build()
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ block := b.CreateBlock()
+ if err := block.AddFact(biscuit.Fact{Predicate: biscuit.Predicate{
+ Name: api.FactNode,
+ IDs: []biscuit.Term{biscuit.String(attacker.String())},
+ }}); err != nil {
+ t.Fatal(err)
+ }
+ attenuated, err := b.Append(cryptorand.Reader, block.Build())
+ if err != nil {
+ t.Fatal(err)
+ }
+ tokenBytes, err := attenuated.Serialize()
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ node := &SamNode{
+ trustedKeys: []TrustedKey{{Key: pub, ReceivedAt: time.Now()}},
+ BiscuitTimeout: 500 * time.Millisecond,
+ }
+
+ req := RequestContext{PeerID: attacker, Protocol: "/test/proto"}
+ if err := node.Authorize(tokenBytes, req, pub); err == nil {
+ t.Fatal("Authorize accepted a token re-bound to the caller by an appended block")
+ }
+}
+
func TestBaselineRules(t *testing.T) {
pub, priv, err := ed25519.GenerateKey(nil)
if err != nil {
diff --git a/internal/node/node.go b/internal/node/node.go
index f83fe45f..0314f9ff 100644
--- a/internal/node/node.go
+++ b/internal/node/node.go
@@ -1433,12 +1433,8 @@ func (n *SamNode) HandleAuthHandshake(s network.Stream) {
}
// 4. Enforce hardware binding: token must include node(<remotePeerID>)
- boundFact := biscuit.Fact{Predicate: biscuit.Predicate{
- Name: "node",
- IDs: []biscuit.Term{biscuit.String(remotePeer.String())},
- }}
- if _, err := b.GetBlockID(boundFact); err != nil {
- logger.Warnf("[AuthN] Token is not bound to peer %s", remotePeer)
+ if err := identity.RequireAuthorityBinding(b, remotePeer); err != nil {
+ logger.Warnf("[AuthN] %v", err)
return
}