Zero Knowledge Caveats for Biscuit Authorization

[prnk28]

In response to #1150

Overview

This post explores implementing Zero Knowledge (ZK) caveats in Biscuit tokens using cryptographic accumulators and witnesses from the BLS signature scheme, with caveat ranges predefined in the Sonr blockchain's x/did module parameters. This approach ensures standardized authorization constraints across the network.

Module Parameters

// x/did/types/params.go
type Params struct {
    // Predefined caveat ranges and constraints
    CaveatRanges map[string]CaveatRange `json:"caveat_ranges"`
    // Maximum number of ZK caveats per token
    MaxZKCaveats uint32 `json:"max_zk_caveats"`
    // Minimum accumulator size
    MinAccumulatorSize uint32 `json:"min_accumulator_size"`
}

type CaveatRange struct {
    // Minimum value for numeric caveats
    Min int64 `json:"min"`
    // Maximum value for numeric caveats
    Max int64 `json:"max"`
    // Allowed values for enumerated caveats
    AllowedValues []string `json:"allowed_values,omitempty"`
    // Time-based caveat constraints
    TimeConstraints *TimeRange `json:"time_constraints,omitempty"`
}

// Param setter in module
func (k Keeper) SetParams(ctx sdk.Context, params Params) {
    k.paramStore.SetParamSet(ctx, &params)
}

Core Components

ZK Accumulator with Module Parameters

// zkp/caveat/accumulator.go
type ZKCaveatAccumulator struct {
    acc *accumulator.Accumulator
    secretKey *bls.SecretKey
    params *types.Params
}

func NewZKCaveatAccumulator(seed []byte, params *types.Params) (*ZKCaveatAccumulator, error) {
    if params.MinAccumulatorSize == 0 {
        return nil, errors.New("invalid accumulator size in module params")
    }
    
    sk := bls.GenerateKey(seed)
    acc := accumulator.NewWithSize(sk, params.MinAccumulatorSize)
    
    return &ZKCaveatAccumulator{
        acc: acc,
        secretKey: sk,
        params: params,
    }, nil
}

func (z *ZKCaveatAccumulator) AddCaveat(caveatType string, value interface{}) (*accumulator.Witness, error) {
    // Verify caveat against predefined ranges
    range, exists := z.params.CaveatRanges[caveatType]
    if !exists {
        return nil, fmt.Errorf("undefined caveat type: %s", caveatType)
    }
    
    if err := validateCaveatValue(value, range); err != nil {
        return nil, fmt.Errorf("invalid caveat value: %w", err)
    }
    
    element := bls.HashToPoint(serializeCaveat(caveatType, value))
    witness, err := z.acc.Add(element)
    if err != nil {
        return nil, fmt.Errorf("failed to add caveat: %w", err)
    }
    
    return witness, nil
}

Parameter-Aware Verifier

// zkp/caveat/verifier.go
type ZKCaveatVerifier struct {
    publicKey *bls.PublicKey
    acc *accumulator.Accumulator
    params *types.Params
}

func (v *ZKCaveatVerifier) VerifyZKCaveat(
    caveatType string,
    value interface{},
    witness *accumulator.Witness,
    proof []byte,
) error {
    // Check against module parameters
    range, exists := v.params.CaveatRanges[caveatType]
    if !exists {
        return errors.New("undefined caveat type")
    }
    
    if err := validateCaveatValue(value, range); err != nil {
        return err
    }
    
    element := bls.HashToPoint(serializeCaveat(caveatType, value))
    
    if !v.acc.VerifyMembership(element, witness) {
        return errors.New("invalid caveat witness")
    }
    
    if !verifyZKProof(proof, element, witness) {
        return errors.New("invalid zero knowledge proof")
    }
    
    return nil
}

Integration with DID Module

// x/did/keeper/msg_server.go
type msgServer struct {
    Keeper
}

func (k msgServer) CreateToken(goCtx context.Context, msg *types.MsgCreateToken) (*types.MsgCreateTokenResponse, error) {
    ctx := sdk.UnwrapSDKContext(goCtx)
    
    // Get module parameters
    params := k.GetParams(ctx)
    
    // Create ZK biscuit builder with params
    builder := NewZKBiscuitBuilder(params)
    
    // Validate against max caveats
    if len(msg.Caveats) > int(params.MaxZKCaveats) {
        return nil, sdkerrors.Wrap(types.ErrTooManyCaveats, "exceeds maximum allowed ZK caveats")
    }
    
    // Add caveats
    for _, caveat := range msg.Caveats {
        if err := builder.AddZKCaveat(caveat.Type, caveat.Value); err != nil {
            return nil, err
        }
    }
    
    token, err := builder.Build()
    if err != nil {
        return nil, err
    }
    
    return &types.MsgCreateTokenResponse{
        Token: token,
    }, nil
}

Example Module Parameters

caveat_ranges:
  time_expiry:
    min: 300  # 5 minutes minimum
    max: 86400  # 24 hours maximum
  
  resource_level:
    allowed_values:
      - "read"
      - "write"
      - "admin"
  
  transaction_amount:
    min: 0
    max: 1000000000  # 1 billion units
    
  network_id:
    allowed_values:
      - "mainnet"
      - "testnet"
      - "devnet"

max_zk_caveats: 10
min_accumulator_size: 1024

Example Usage with Module Parameters

// Get module parameters from chain
params := didKeeper.GetParams(ctx)

// Create new ZK-enabled biscuit
builder := NewZKBiscuitBuilder(params)

// Add private caveats (will be validated against params)
builder.AddZKCaveat("time_expiry", time.Now().Add(1 * time.Hour).Unix())
builder.AddZKCaveat("resource_level", "write")
builder.AddZKCaveat("transaction_amount", 5000)
builder.AddZKCaveat("network_id", "mainnet")

// Build token
token, err := builder.Build()
if err != nil {
    panic(err)
}

// Verify token with ZK caveats
verifier := NewZKBiscuitVerifier(params)
if err := verifier.Verify(token); err != nil {
    // Handle verification failure
}

Benefits

1. Standardized Constraints: Caveat ranges enforced at protocol level
2. Network-wide Consistency: All tokens follow the same parameter rules
3. Governance Control: Parameters can be updated through governance proposals
4. Resource Protection: Prevents abuse through maximum caveat limits
5. Predictable Behavior: Well-defined ranges for all caveat types

Implementation Details

Parameter Validation

func validateCaveatValue(value interface{}, range CaveatRange) error {
    switch v := value.(type) {
    case int64:
        if v < range.Min || v > range.Max {
            return fmt.Errorf("value %d outside allowed range [%d, %d]", 
                v, range.Min, range.Max)
        }
    case string:
        if !slices.Contains(range.AllowedValues, v) {
            return fmt.Errorf("value %s not in allowed values: %v", 
                v, range.AllowedValues)
        }
    default:
        return fmt.Errorf("unsupported caveat value type: %T", value)
    }
    return nil
}

Parameter Updates

// x/did/keeper/params.go
func (k Keeper) UpdateParams(ctx sdk.Context, authority string, updates types.ParamChanges) error {
    if !k.HasAuthority(authority) {
        return sdkerrors.Wrap(types.ErrUnauthorized, "invalid authority")
    }
    
    params := k.GetParams(ctx)
    
    // Apply updates
    if err := params.Update(updates); err != nil {
        return err
    }
    
    // Validate new params
    if err := params.Validate(); err != nil {
        return err
    }
    
    // Store updated params
    k.SetParams(ctx, params)
    
    return nil
}

Future Improvements

1. Add dynamic range updates based on network metrics
2. Implement parameter-specific ZK proof optimizations
3. Add cross-chain parameter synchronization
4. Support for composite caveat ranges
5. Add parameter migration strategies

Security Considerations

1. Parameter update authorization controls
2. Range boundary validation
3. Accumulator size requirements
4. Parameter storage security
5. Update frequency limitations

This implementation provides a standardized approach to ZK caveats in Biscuit authorization by leveraging the Sonr blockchain's x/did module parameters. This ensures consistent and governable authorization constraints across the entire network while maintaining privacy through zero knowledge proofs.

For more implementation details, refer to the cryptographic primitives in the [onsonr/crypto](https://github.com/onsonr/crypto) repository and the DID module documentation.