@openverb/policy 2.0.0-alpha.4 → 2.0.0-alpha.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +140 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
# @openverb/policy
|
|
2
|
+
|
|
3
|
+
Policy engine for the OpenVerb Framework - tier-based authorization and access control.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
```bash
|
|
7
|
+
npm install @openverb/policy @openverb/runtime
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
## Quick Start
|
|
11
|
+
```typescript
|
|
12
|
+
import { createPolicyEngine } from '@openverb/policy'
|
|
13
|
+
|
|
14
|
+
const policy = createPolicyEngine({
|
|
15
|
+
tiers: [
|
|
16
|
+
{
|
|
17
|
+
id: 'free',
|
|
18
|
+
allow: {
|
|
19
|
+
effects: ['db.read'],
|
|
20
|
+
verbs: ['user.get', 'user.list']
|
|
21
|
+
},
|
|
22
|
+
quotas: {
|
|
23
|
+
'api.requests': { limit: 100, window: '1h' }
|
|
24
|
+
}
|
|
25
|
+
},
|
|
26
|
+
{
|
|
27
|
+
id: 'pro',
|
|
28
|
+
allow: {
|
|
29
|
+
effects: ['db.read', 'db.write', 'email.send']
|
|
30
|
+
},
|
|
31
|
+
quotas: {
|
|
32
|
+
'api.requests': { limit: 10000, window: '1h' }
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
]
|
|
36
|
+
})
|
|
37
|
+
|
|
38
|
+
// Check if an action is allowed
|
|
39
|
+
const decision = policy.evaluate({
|
|
40
|
+
verbId: 'user.create',
|
|
41
|
+
effects: ['db.write'],
|
|
42
|
+
actor: { type: 'user', id: 'user-123' },
|
|
43
|
+
context: { tenantId: 'acme', planId: 'free' }
|
|
44
|
+
})
|
|
45
|
+
|
|
46
|
+
console.log(decision)
|
|
47
|
+
// {
|
|
48
|
+
// decision: 'deny',
|
|
49
|
+
// reasons: ['not_in_tier_allowlist'],
|
|
50
|
+
// code: 'not_allowed',
|
|
51
|
+
// message: 'This action is not included in your plan',
|
|
52
|
+
// upsell: {
|
|
53
|
+
// suggestedPlanId: 'pro',
|
|
54
|
+
// cta: 'Upgrade to unlock'
|
|
55
|
+
// }
|
|
56
|
+
// }
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## Tier Configuration
|
|
60
|
+
|
|
61
|
+
### Allow Lists
|
|
62
|
+
|
|
63
|
+
Control access by effects or specific verbs:
|
|
64
|
+
```typescript
|
|
65
|
+
{
|
|
66
|
+
id: 'enterprise',
|
|
67
|
+
allow: {
|
|
68
|
+
effects: ['*'], // Allow all effects
|
|
69
|
+
verbs: ['admin.*'] // Allow all admin verbs
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
### Quotas
|
|
75
|
+
|
|
76
|
+
Rate limiting and usage quotas:
|
|
77
|
+
```typescript
|
|
78
|
+
{
|
|
79
|
+
id: 'free',
|
|
80
|
+
quotas: {
|
|
81
|
+
'api.requests': {
|
|
82
|
+
limit: 100,
|
|
83
|
+
window: '1h' // 100 requests per hour
|
|
84
|
+
},
|
|
85
|
+
'storage.bytes': {
|
|
86
|
+
limit: 1000000000 // 1GB total
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
## Integration with Runtime
|
|
93
|
+
```typescript
|
|
94
|
+
import { createRuntime } from '@openverb/runtime'
|
|
95
|
+
import { createPolicyEngine } from '@openverb/policy'
|
|
96
|
+
|
|
97
|
+
const policy = createPolicyEngine({ tiers: [...] })
|
|
98
|
+
|
|
99
|
+
const runtime = createRuntime({
|
|
100
|
+
verbs,
|
|
101
|
+
handlers,
|
|
102
|
+
policy, // Add policy engine
|
|
103
|
+
adapters
|
|
104
|
+
})
|
|
105
|
+
|
|
106
|
+
// Now all executions are automatically checked against policies
|
|
107
|
+
const result = await runtime.execute({
|
|
108
|
+
verbId: 'premium.feature',
|
|
109
|
+
args: {},
|
|
110
|
+
actor: { type: 'user', id: 'user-123' },
|
|
111
|
+
context: {
|
|
112
|
+
tenantId: 'acme',
|
|
113
|
+
planId: 'free' // Policy engine checks this
|
|
114
|
+
}
|
|
115
|
+
})
|
|
116
|
+
|
|
117
|
+
// If denied:
|
|
118
|
+
// {
|
|
119
|
+
// ok: false,
|
|
120
|
+
// denied: true,
|
|
121
|
+
// reason: { code: 'not_allowed', message: '...' },
|
|
122
|
+
// upsell: { suggestedPlanId: 'pro', cta: 'Upgrade to unlock' }
|
|
123
|
+
// }
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
## Policy Decision Types
|
|
127
|
+
|
|
128
|
+
- `allow` - Action is permitted
|
|
129
|
+
- `deny` - Action is not permitted
|
|
130
|
+
- Reasons include: `not_in_tier_allowlist`, `quota_exceeded`, `role_required`
|
|
131
|
+
|
|
132
|
+
## Related Packages
|
|
133
|
+
|
|
134
|
+
- [@openverb/runtime](https://www.npmjs.com/package/@openverb/runtime) - Execution runtime
|
|
135
|
+
- [@openverb/sdk](https://www.npmjs.com/package/@openverb/sdk) - Client SDK
|
|
136
|
+
- [@openverb/cli](https://www.npmjs.com/package/@openverb/cli) - CLI tools
|
|
137
|
+
|
|
138
|
+
## License
|
|
139
|
+
|
|
140
|
+
MIT
|