open-index/open-npm huggingface dataset:
npm package: @openverb/policy
Description: OpenVerb policy engine
Latest version: 2.0.0-alpha.6

# @openverb/policy

Policy engine for the OpenVerb Framework - tier-based authorization and access control.

## Installation
```bash
npm install @openverb/policy @openverb/runtime
```

## Quick Start
```typescript
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:
```typescript
{
  id: 'enterprise',
  allow: {
    effects: ['*'],              // Allow all effects
    verbs: ['admin.*']           // Allow all admin verbs
  }
}
```

### Quotas

Rate limiting and usage quotas:
```typescript
{
  id: 'free',
  quotas: {
    'api.requests': { 
      limit: 100, 
      window: '1h'     // 100 requests per hour
    },
    'storage.bytes': { 
      limit: 1000000000  // 1GB total
    }
  }
}
```

## Integration with Runtime
```typescript
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](https://www.npmjs.com/package/@openverb/runtime) - Execution runtime
- [@openverb/sdk](https://www.npmjs.com/package/@openverb/sdk) - Client SDK
- [@openverb/cli](https://www.npmjs.com/package/@openverb/cli) - CLI tools

## License

MIT