Skip to content

Commit 2400d70

Browse files
monkenmonken
committed
docs, release
1 parent 68cb7ab commit 2400d70

File tree

4 files changed

+230
-70
lines changed

4 files changed

+230
-70
lines changed

‎README.md‎

Lines changed: 97 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,84 +1,144 @@
1-
[![Build Status](https://travis-ci.org/monken/node-pbac.svg?branch=master)](https://travis-ci.org/monken/node-pbac)
1+
[![npm](http://img.shields.io/npm/v/jsdox.svg)](https://npmjs.org/package/pbac) [![npm](http://img.shields.io/npm/dm/pbac.svg)](https://npmjs.org/package/jsdox) [![Build Status](https://travis-ci.org/monken/node-pbac.svg?branch=master)](https://travis-ci.org/monken/node-pbac)
22

3-
# node-pbac
3+
# Policy Based Access Control
4+
5+
**AWS IAM Policy compatible evaluation engine**
6+
7+
Use the power and flexibility of the AWS IAM Policy syntax in your own application to manage access control. For more details on AWS IAM Policies have a look at https://docs.aws.amazon.com/IAM/latest/UserGuide/policies_overview.html.
8+
9+
**Note:** The policy elements `Principal`, `NotPrincipal`, `NotResource` and conditions `ArnEquals`, `ArnNotEquals`, `ArnLike`, `ArnNotLike` are not supported at the moment.
410

511
## Installation
612

713
```
814
npm install pbac
915
```
1016

11-
1217
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
1318
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
1419
Contents
1520

16-
- [Global](#global)
17-
- [Class: PBAC](#class-pbac)
18-
- [PBAC.Klass()](#pbacklass)
19-
- [PBAC.validate(policy)](#pbacvalidatepolicy)
20-
- [PBAC.evaluate(object)](#pbacevaluateobject)
21+
- [Synopsis](#synopsis)
22+
- [Constructor](#constructor)
23+
- [Properties](#properties)
24+
- [Methods](#methods)
25+
- [evaluate(params)](#evaluateparams)
26+
- [validate(policy)](#validatepolicy)
2127

2228
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
23-
# Global
24-
25-
26-
27-
2829

29-
* * *
30+
## Synopsis
3031

31-
## Class: PBAC
32+
```javascript
33+
var PBAC = require('pbac');
3234

35+
var policies = [{
36+
"Version": "2012-10-17",
37+
"Statement": [{
38+
"Sid": "OptionalDescription",
39+
"Effect": "Allow",
40+
"Action": [
41+
"iam:CreateUser",
42+
"iam:UpdateUser",
43+
"iam:DeleteUser"
44+
],
45+
"Resource": [
46+
"arn:aws:iam:::user/${req:UserName}"
47+
],
48+
"Condition": {
49+
"IpAddress": {
50+
"req:IpAddress": "10.0.20.0/24"
51+
}
52+
}
53+
}]
54+
}];
55+
56+
var pbac = new PBAC(policies);
57+
58+
// returns true
59+
pbac.evaluate({
60+
action: 'iam:CreateUser',
61+
resource: 'arn:aws:iam:::user/testuser',
62+
variables: {
63+
req: {
64+
IpAddress: '10.0.20.51',
65+
UserName: 'testuser',
66+
}
67+
}
68+
});
69+
```
3370

34-
### PBAC.Klass()
71+
## Constructor
3572

73+
```javascript
74+
var pbac = new PBAC(policies, [options]);
3675
```
37-
var PBAC = require('pbac');
38-
var pbac = new PBAC({
3976

40-
});
41-
```
77+
Constructs a policy evaluator.
4278

79+
### Properties
4380

44-
### PBAC.validate(policy)
4581

46-
Validates one or many policies against the schema provided in the constructor.
47-
Will throw an error if validation fails.
82+
* **`policies`** (Array|Object)
83+
Either an array of policies or a single policy document. Have a look at https://docs.aws.amazon.com/IAM/latest/UserGuide/AccessPolicyLanguage_ElementDescriptions.html for a description of the policy syntax.
84+
* **`options`** (Object)
85+
* `schema` (Object)
86+
JSON schema that describes the policies. Defaults to the contents of schema.json that ships with this module.
87+
* `validateSchema` (Boolean)
88+
Validate the schema when the object is constructed. This can be disabled in a production environment if it can be assumed that the schema is valid to improve performance when constructing new objects.
89+
* `validatePolicies` (Boolean)
90+
Policies passed to the constructor will be validated against the `schema`. Defaults to `true`. Can be disabled to improve performance if the policies can be assumed to be valid.
91+
* `conditions` (Object)
92+
Object of conditions that are supported in the `Conditions` attribute of policies. Defaults to `conditions.js` in this module. If conditions are passed to the constructor they will be merged with the conditions of the `conditions.js` module (with `conditions.js` taking precedence).
4893

49-
**Parameters**
5094

51-
**policy**: `Object`, Array of policies or single policy object
95+
## Methods
5296

53-
**Returns**: `Bool`, Returns `true` if the policies are valid
5497

55-
### PBAC.evaluate(object)
98+
### evaluate(params)
5699

57100
Tests an object against the policies and determines if the object passes.
58101
The method will first try to find a policy with an explicit `Deny` for the combination of
59102
`resource`, `action` and `condition` (matching policy). If such policy exists, `evaulate` returns false.
60103
If there is no explicit deny the method will look for a matching policy with an explicit `Allow`.
61104
`evaulate` will return `true` if such a policy is found. If no matching can be found at all,
62-
`evaluate` will return `false`.
105+
`evaluate` will return `false`. Please find a more thorough explanation of this process at https://docs.aws.amazon.com/IAM/latest/UserGuide/AccessPolicyLanguage_EvaluationLogic.html.
106+
107+
```javascript
108+
pbac.evaluate({
109+
action: 'iam:CreateUser',
110+
resource: 'arn:aws:iam:::user/testuser',
111+
variables: {
112+
req: {
113+
IpAddress: '10.0.20.51',
114+
UserName: 'testuser',
115+
}
116+
}
117+
});
118+
```
63119

64120
**Parameters**
65121

66-
**object**: `Object`, Object to test against the policies
67-
68-
**Returns**: `Bool`, Returns `true` if the object passes, `false` otherwise
69-
70-
71-
72-
* * *
73-
74-
122+
* **`params`** (Object)
123+
* `action` (String) - Action to validate
124+
* `resource` (String) - Resource to validate
125+
* `variables` (Object) - Nested object of variables for interpolation of policy variables. See [Variables]().
75126

127+
**Returns**: `boolean`, Returns `true` if `params` passes the policies, `false` otherwise
76128

129+
### validate(policy)
77130

131+
Validates one or many policies against the schema provided in the constructor.
132+
Will throw an error if validation fails.
78133

134+
**Parameters**
79135

136+
* **`policy`** (Array|Object)
137+
Array of policies or a single policy object
80138

139+
**Returns**: `boolean`, Returns `true` if the policies are valid
81140

141+
* * *
82142

83143
The MIT License (MIT)
84144

‎output/intro.md‎

Lines changed: 122 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,132 @@
1-
[![Build Status](https://travis-ci.org/monken/node-pbac.svg?branch=master)](https://travis-ci.org/monken/node-pbac)
1+
[![npm](http://img.shields.io/npm/v/jsdox.svg)](https://npmjs.org/package/pbac) [![npm](http://img.shields.io/npm/dm/pbac.svg)](https://npmjs.org/package/jsdox) [![Build Status](https://travis-ci.org/monken/node-pbac.svg?branch=master)](https://travis-ci.org/monken/node-pbac)
22

3-
# node-pbac
3+
# Policy Based Access Control
4+
5+
**AWS IAM Policy compatible evaluation engine**
6+
7+
Use the power and flexibility of the AWS IAM Policy syntax in your own application to manage access control. For more details on AWS IAM Policies have a look at https://docs.aws.amazon.com/IAM/latest/UserGuide/policies_overview.html.
8+
9+
**Note:** The policy elements `Principal`, `NotPrincipal`, `NotResource` and conditions `ArnEquals`, `ArnNotEquals`, `ArnLike`, `ArnNotLike` are not supported at the moment.
410

511
## Installation
612

713
```
814
npm install pbac
915
```
1016

11-
1217
<!-- START doctoc -->
1318
<!-- END doctoc -->
19+
20+
## Synopsis
21+
22+
```javascript
23+
var PBAC = require('pbac');
24+
25+
var policies = [{
26+
"Version": "2012-10-17",
27+
"Statement": [{
28+
"Sid": "OptionalDescription",
29+
"Effect": "Allow",
30+
"Action": [
31+
"iam:CreateUser",
32+
"iam:UpdateUser",
33+
"iam:DeleteUser"
34+
],
35+
"Resource": [
36+
"arn:aws:iam:::user/${req:UserName}"
37+
],
38+
"Condition": {
39+
"IpAddress": {
40+
"req:IpAddress": "10.0.20.0/24"
41+
}
42+
}
43+
}]
44+
}];
45+
46+
var pbac = new PBAC(policies);
47+
48+
// returns true
49+
pbac.evaluate({
50+
action: 'iam:CreateUser',
51+
resource: 'arn:aws:iam:::user/testuser',
52+
variables: {
53+
req: {
54+
IpAddress: '10.0.20.51',
55+
UserName: 'testuser',
56+
}
57+
}
58+
});
59+
```
60+
61+
## Constructor
62+
63+
```javascript
64+
var pbac = new PBAC(policies, [options]);
65+
```
66+
67+
Constructs a policy evaluator.
68+
69+
### Properties
70+
71+
72+
* **`policies`** (Array|Object)
73+
Either an array of policies or a single policy document. Have a look at https://docs.aws.amazon.com/IAM/latest/UserGuide/AccessPolicyLanguage_ElementDescriptions.html for a description of the policy syntax.
74+
* **`options`** (Object)
75+
* `schema` (Object)
76+
JSON schema that describes the policies. Defaults to the contents of `schema.json` that ships with this module.
77+
* `validateSchema` (Boolean)
78+
Validate the schema when the object is constructed. This can be disabled in a production environment if it can be assumed that the schema is valid to improve performance when constructing new objects.
79+
* `validatePolicies` (Boolean)
80+
Policies passed to the constructor will be validated against the `schema`. Defaults to `true`. Can be disabled to improve performance if the policies can be assumed to be valid.
81+
* `conditions` (Object)
82+
Object of conditions that are supported in the `Conditions` attribute of policies. Defaults to `conditions.js` in this module. If conditions are passed to the constructor they will be merged with the conditions of the `conditions.js` module (with `conditions.js` taking precedence).
83+
84+
85+
## Methods
86+
87+
88+
### evaluate(params)
89+
90+
Tests an object against the policies and determines if the object passes.
91+
The method will first try to find a policy with an explicit `Deny` for the combination of
92+
`resource`, `action` and `condition` (matching policy). If such policy exists, `evaulate` returns false.
93+
If there is no explicit deny the method will look for a matching policy with an explicit `Allow`.
94+
`evaulate` will return `true` if such a policy is found. If no matching can be found at all,
95+
`evaluate` will return `false`. Please find a more thorough explanation of this process at https://docs.aws.amazon.com/IAM/latest/UserGuide/AccessPolicyLanguage_EvaluationLogic.html.
96+
97+
```javascript
98+
pbac.evaluate({
99+
action: 'iam:CreateUser',
100+
resource: 'arn:aws:iam:::user/testuser',
101+
variables: {
102+
req: {
103+
IpAddress: '10.0.20.51',
104+
UserName: 'testuser',
105+
}
106+
}
107+
});
108+
```
109+
110+
**Parameters**
111+
112+
* **`params`** (Object)
113+
* `action` (String) - Action to validate
114+
* `resource` (String) - Resource to validate
115+
* `variables` (Object) - Nested object of variables for interpolation of policy variables. See [Variables]().
116+
117+
**Returns**: `boolean`, Returns `true` if `params` passes the policies, `false` otherwise
118+
119+
### validate(policy)
120+
121+
Validates one or many policies against the schema provided in the constructor.
122+
Will throw an error if validation fails.
123+
124+
**Parameters**
125+
126+
* **`policy`** (Array|Object)
127+
Array of policies or a single policy object
128+
129+
**Returns**: `boolean`, Returns `true` if the policies are valid
130+
131+
* * *
132+

‎package.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
{
22
"name": "pbac",
3-
"version": "0.0.1",
3+
"version": "0.1.0",
44
"dependencies": {
55
"ipcheck": "^0.1.0",
66
"lodash": "^3.10.0",
77
"z-schema": "^3.12.0"
88
},
99
"scripts": {
1010
"test": "mocha --bail t/",
11-
"docs": "jsdox -i index . && cat output/{intro,pbac}.md LICENSE > README.md && doctoc --title Contents README.md"
11+
"docs": "cat output/intro.md LICENSE > README.md && doctoc --title Contents README.md"
1212
},
1313
"devDependencies": {
1414
"doctoc": "^0.14.2",

0 commit comments

Comments
 (0)