core/docs/internal/rules-API_SPECIFICATION.md

Authorization Rules API Specification

This document defines the standardized API that all authorization rules must implement to ensure consistency, performance, and maintainability across the zanzibar-graph system.

Overview

All authorization rules must extend the BaseRule class and implement the required abstract methods. This ensures:

• Consistent Interface: All rules have the same public API
• Performance Tracking: Built-in performance monitoring
• Error Handling: Standardized error responses
• Batch Processing: Optional but encouraged for performance
• Early Exit: Threshold-based optimization support
• Input Validation: Automatic parameter validation

Core Interface

Constructor

constructor(arbiter)

Parameters:

• arbiter (Arbiter): The main Arbiter instance

Requirements:

• Must call super(arbiter) first
• Should initialize any rule-specific state
• Must not throw exceptions

Primary Evaluation Method

evaluate(userId, userKey, objectId, objectKey, rule, visited, currentRelation, options = {})

Parameters:

• userId (number): Internal user node ID
• userKey (string): User key (e.g., "user:alice")
• objectId (number): Internal object node ID
• objectKey (string): Object key (e.g., "doc:secret")
• rule (Object): Rule configuration object
• visited (Set): Set of visited nodes for cycle detection
• currentRelation (string): Current relation being evaluated
• options (Object): Evaluation options

Returns: RuleEvaluationResult object

Standard Options:

{
  // Performance options
  fastPath: false,                    // Enable early termination
  minAllowPossibility: null,          // Threshold for allow early exit (0-1)
  maxDenyPossibility: null,           // Threshold for deny early exit (0-1)
  
  // Inference options
  noInfer: false,                     // Disable inference
  allowInference: true,               // Allow inference (opposite of noInfer)
  
  // Binary mode
  binary: false,                      // Return binary allow/deny decisions
  
  // Evaluation tracking
  trackEvaluation: true,              // Include evaluation metadata
  
  // Rule-specific options (passed through)
  // ... additional options specific to rule type
}

Batch Evaluation Method (Optional)

batchEvaluate(queries, batchOptions = {})

Parameters:

• queries (Array): Array of query objects with same structure as evaluate parameters
• batchOptions (Object): Batch-specific options

Returns: Array of RuleEvaluationResult objects

Query Object Structure:

{
  userId: number,
  userKey: string,
  objectId: number,
  objectKey: string,
  rule: Object,
  visited: Set,
  currentRelation: string,
  options: Object
}

Batch Support Check

canBatchProcess()

Returns: boolean - Whether this rule supports efficient batch processing

Standard Result Structure

All evaluation methods must return a RuleEvaluationResult object:

{
  // Core evaluation results (required)
  possibility_allow: number,          // 0-1, possibility of allowing access
  possibility_deny: number,           // 0-1, possibility of denying access
  reliability: number,                // 0-1, reliability of the evaluation
  
  // Metadata (required, can be null)
  meta_allow: Object | null,          // Metadata for allow decision
  meta_deny: Object | null,           // Metadata for deny decision
  
  // Optional fields
  reason: string,                     // Reason for the result
  error: boolean,                     // Whether this is an error result
  details: Object,                    // Additional details
  evaluation: Object                  // Evaluation tracking data
}

Standard Metadata Structure

// meta_allow / meta_deny structure
{
  ruleType: string,                   // Type of rule (e.g., 'direct', 'tuple_to_userset')
  reason: string,                     // Reason for decision
  rule: Object,                       // Original rule configuration
  
  // Performance metadata
  earlyExit: boolean,                 // Whether early exit was used
  earlyExitReason: string,            // Reason for early exit
  
  // Rule-specific metadata
  // ... additional fields specific to rule type
}

Implementation Requirements

Abstract Methods (Must Implement)

// Core evaluation logic
_evaluateRule(userId, userKey, objectId, objectKey, rule, visited, currentRelation, options)

// Batch evaluation logic (optional, only if canBatchProcess() returns true)
_batchEvaluateRule(queries, batchOptions)

Performance Tracking

All rules automatically track:

• Individual evaluation count and timing
• Batch evaluation count and timing
• Average evaluation times

Access via:

rule.getPerformanceStats()
rule.resetPerformanceStats()

Error Handling

Rules should handle errors gracefully:

• Input validation is automatic
• Exceptions are caught and converted to error results
• Batch operations fall back to individual evaluations on error

Rule-Specific Configurations

Common Rule Properties

{
  type: string,                       // Rule type identifier
  ruleType: string,                   // 'defeasible', 'defeater', 'strict'
  priority: number,                   // Rule priority (higher = more important)
  weight: number,                     // Rule weight for aggregation
  
  // Performance options
  no_infer: boolean,                  // Disable inference for this rule
  allowInference: boolean,            // Allow inference
  
  // Aggregation options
  owaWeights: Array<number>,          // OWA aggregation weights
  aggregator: string,                 // Aggregation method ('max', 'min', 'avg', etc.)
  
  // Rule-specific properties
  // ... varies by rule type
}

DirectRule Configuration

{
  type: 'direct',
  relation: string,                   // Relation to check (optional, uses currentRelation)
  reverse: boolean                    // Check in reverse direction
}

TupleToUsersetRule Configuration

{
  type: 'tuple_to_userset',
  tuplesetRelation: string,           // Relation from object to intermediate
  computedRelation: string,           // Relation from user to intermediate
  reverse: boolean                    // Check in reverse direction
}

ParentRule Configuration

{
  type: 'parent',
  parentRelation: string,             // Relation defining parent-child
  relation: string,                   // Relation to check on parent
  reverse: boolean                    // Check in reverse direction
}

SimilarityRule Configuration

{
  type: 'similar_to',
  relation: string,                   // Relation to find similarities for
  k: number,                          // Number of similar entities to consider
  similarityThreshold: number,        // Minimum similarity threshold (0-1)
  reverse: boolean,                   // Check in reverse direction
  fallbackToBasicSimilarity: boolean  // Use basic similarity when embeddings unavailable
}

MultiHopRule Configuration

{
  type: 'multi_hop',
  relation: string,                   // Relation to traverse
  maxDepth: number,                   // Maximum path depth
  minReliability: number,             // Minimum path reliability
  decayFactor: number,                // Reliability decay per hop
  pathAggregation: string,            // How to aggregate multiple paths ('max', 'sum', 'owa')
  reverse: boolean,                   // Search in reverse direction
  allowInference: boolean,            // Allow inference for missing edges
  fallbackToBasicPaths: boolean       // Use basic path finding as fallback
}

ComputedRule Configuration

{
  type: 'computed',
  relation: string                    // Relation to recursively evaluate
}

Logical Operators

Union (OR) Configuration

{
  union: Array<RuleConfig>,           // Array of rules to OR together
  aggregator: string,                 // Aggregation method
  owaWeights: Array<number>,          // OWA weights for fusion
  reliabilityWeighting: boolean       // Weight by reliability
}

Intersection (AND) Configuration

{
  intersection: Array<RuleConfig>,    // Array of rules to AND together
  aggregator: string,                 // Aggregation method (defaults to 'min')
  owaWeights: Array<number>           // OWA weights for fusion
}

Exclusion (A AND NOT B) Configuration

{
  exclusion: [RuleConfig, RuleConfig] // [base rule, exclusion rule]
}

Performance Optimization Guidelines

Early Exit Support

Rules should support early termination when:

• options.fastPath is true
• options.minAllowPossibility threshold is met
• options.maxDenyPossibility threshold is met

Batch Processing

Rules that can benefit from batch processing should:

• Override canBatchProcess() to return true
• Implement _batchEvaluateRule() method
• Group similar operations for efficiency
• Use indexed lookups instead of linear scans

Caching

Rules should leverage:

• Arbiter's built-in caching mechanisms
• Batch caches for intermediate results
• Embedding caches for similarity calculations

Testing Requirements

All rules must include:

• Unit tests for individual evaluation
• Batch evaluation tests (if supported)
• Performance benchmarks
• Error handling tests
• Edge case coverage

Migration Guide

To migrate existing rules to the new API:

1. Extend BaseRule: Change export class MyRule to export class MyRule extends BaseRule
2. Rename evaluate: Rename evaluate() to _evaluateRule()
3. Update constructor: Call super(arbiter) first
4. Handle options: Use normalized options parameter
5. Update tests: Test against new interface

Example Implementation

import { BaseRule } from './BaseRule.js';

export class ExampleRule extends BaseRule {
  constructor(arbiter) {
    super(arbiter);
    // Rule-specific initialization
  }

  canBatchProcess() {
    return true; // This rule supports batching
  }

  _evaluateRule(userId, userKey, objectId, objectKey, rule, visited, currentRelation, options) {
    // Implement rule-specific logic
    const result = {
      possibility_allow: 0.8,
      possibility_deny: 0.1,
      reliability: 0.9,
      meta_allow: {
        ruleType: 'example',
        reason: 'example_evaluation',
        rule
      },
      meta_deny: null,
      reason: 'example_result'
    };

    return result;
  }

  _batchEvaluateRule(queries, batchOptions) {
    // Implement efficient batch processing
    return queries.map(query => 
      this._evaluateRule(
        query.userId, 
        query.userKey, 
        query.objectId, 
        query.objectKey, 
        query.rule, 
        query.visited, 
        query.currentRelation, 
        query.options
      )
    );
  }
}

This standardized API ensures all rules work consistently while allowing for rule-specific optimizations and features.