@openverb/policy

Policy engine for the OpenVerb Framework - tier-based authorization and access control.

Installation

npm install @openverb/policy @openverb/runtime

Quick Start

import { createPolicyEngine } from '@openverb/policy'

const policy = createPolicyEngine({
  tiers: [
    {
      id: 'free',
      allow: {
        effects: ['db.read'],
        verbs: ['user.get', 'user.list']
      },
      quotas: {
        'api.requests': { limit: 100, window: '1h' }
      }
    },
    {
      id: 'pro',
      allow: {
        effects: ['db.read', 'db.write', 'email.send']
      },
      quotas: {
        'api.requests': { limit: 10000, window: '1h' }
      }
    }
  ]
})

// Check if an action is allowed
const decision = policy.evaluate({
  verbId: 'user.create',
  effects: ['db.write'],
  actor: { type: 'user', id: 'user-123' },
  context: { tenantId: 'acme', planId: 'free' }
})

console.log(decision)
// {
//   decision: 'deny',
//   reasons: ['not_in_tier_allowlist'],
//   code: 'not_allowed',
//   message: 'This action is not included in your plan',
//   upsell: {
//     suggestedPlanId: 'pro',
//     cta: 'Upgrade to unlock'
//   }
// }

Tier Configuration

Allow Lists

Control access by effects or specific verbs:

{
  id: 'enterprise',
  allow: {
    effects: ['*'],              // Allow all effects
    verbs: ['admin.*']           // Allow all admin verbs
  }
}

Quotas

Rate limiting and usage quotas:

{
  id: 'free',
  quotas: {
    'api.requests': { 
      limit: 100, 
      window: '1h'     // 100 requests per hour
    },
    'storage.bytes': { 
      limit: 1000000000  // 1GB total
    }
  }
}

Integration with Runtime

import { createRuntime } from '@openverb/runtime'
import { createPolicyEngine } from '@openverb/policy'

const policy = createPolicyEngine({ tiers: [...] })

const runtime = createRuntime({
  verbs,
  handlers,
  policy,  // Add policy engine
  adapters
})

// Now all executions are automatically checked against policies
const result = await runtime.execute({
  verbId: 'premium.feature',
  args: {},
  actor: { type: 'user', id: 'user-123' },
  context: { 
    tenantId: 'acme', 
    planId: 'free'  // Policy engine checks this
  }
})

// If denied:
// {
//   ok: false,
//   denied: true,
//   reason: { code: 'not_allowed', message: '...' },
//   upsell: { suggestedPlanId: 'pro', cta: 'Upgrade to unlock' }
// }

Policy Decision Types

• allow - Action is permitted
• deny - Action is not permitted
• Reasons include: not_in_tier_allowlist, quota_exceeded, role_required

Related Packages

• @openverb/runtime - Execution runtime
• @openverb/sdk - Client SDK
• @openverb/cli - CLI tools

License

MIT