Skip to content

Commit 01c52ab

Browse files
getlargegetlarge
committed
docs: add minimal documentatioon for packages
1 parent 5c4aa29 commit 01c52ab

File tree

5 files changed

+298
-59
lines changed

5 files changed

+298
-59
lines changed

‎README.md‎

Lines changed: 9 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -1,57 +1,17 @@
11
# NestJS Ory Integration
22

3-
<a alt="Nx logo" href="https://nx.dev" target="_blank" rel="noreferrer"><img src="https://raw.githubusercontent.com/nrwl/nx/master/images/nx-logo.png" width="45"></a>
3+
This is a monorepo containing the following packages:
44

5-
✨ **This workspace has been generated by [Nx, a Smart, fast and extensible build system.](https://nx.dev)** ✨
5+
- [keto-client-wrapper](./packages/keto-client-wrapper/README.md)
6+
- [keto-relations-parser](./packages/keto-relations-parser/README.md)
7+
- [kratos-client-wrapper](./packages/kratos-client-wrapper/README.md)
68

7-
## Generate code
9+
These packages are used to integrate [Ory Keto](https://www.ory.sh/keto/docs/) and [Ory Kratos](https://www.ory.sh/kratos/docs/) with [NestJS](https://nestjs.com/).
810

9-
If you happen to use Nx plugins, you can leverage code generators that might come with it.
11+
## Installation and usage
1012

11-
Run `nx list` to get a list of available plugins and whether they have generators. Then run `nx list <plugin-name>` to see what generators are available.
13+
Check the README of each package for more details.
1214

13-
Learn more about [Nx generators on the docs](https://nx.dev/plugin-features/use-code-generators).
15+
## Examples
1416

15-
## Running tasks
16-
17-
To execute tasks with Nx use the following syntax:
18-
19-
```
20-
nx <target> <project> <...options>
21-
```
22-
23-
You can also run multiple targets:
24-
25-
```
26-
nx run-many -t <target1> <target2>
27-
```
28-
29-
..or add `-p` to filter specific projects
30-
31-
```
32-
nx run-many -t <target1> <target2> -p <proj1> <proj2>
33-
```
34-
35-
Targets can be defined in the `package.json` or `projects.json`. Learn more [in the docs](https://nx.dev/core-features/run-tasks).
36-
37-
## Want better Editor Integration?
38-
39-
Have a look at the [Nx Console extensions](https://nx.dev/nx-console). It provides autocomplete support, a UI for exploring and running tasks & generators, and more! Available for VSCode, IntelliJ and comes with a LSP for Vim users.
40-
41-
## Ready to deploy?
42-
43-
Just run `nx build demoapp` to build the application. The build artifacts will be stored in the `dist/` directory, ready to be deployed.
44-
45-
## Set up CI!
46-
47-
Nx comes with local caching already built-in (check your `nx.json`). On CI you might want to go a step further.
48-
49-
- [Set up remote caching](https://nx.dev/core-features/share-your-cache)
50-
- [Set up task distribution across multiple machines](https://nx.dev/nx-cloud/features/distribute-task-execution)
51-
- [Learn more how to setup CI](https://nx.dev/recipes/ci)
52-
53-
## Connect with us!
54-
55-
- [Join the community](https://nx.dev/community)
56-
- [Subscribe to the Nx Youtube Channel](https://www.youtube.com/@nxdevtools)
57-
- [Follow us on Twitter](https://twitter.com/nxdevtools)
17+
Check the [ticketing repository](https://github.com/getlarge/ticketing) for a real world example of how to use these packages.

‎packages/keto-client-wrapper/README.md‎

Lines changed: 93 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,101 @@
11
# keto-client-wrapper
22

3-
This library was generated with [Nx](https://nx.dev).
3+
This library is a wrapper around the [Ory Keto](https://www.ory.sh/keto/docs/) client - [@ory/client](https://github.com/ory/client-js). It provides :
44

5-
## Building
5+
- OryRelationshipsModule: a module to interact with the Ory Keto Relationships API
6+
- OryPermissionsModule: a module to interact with the Ory Keto Permissions API
7+
- OryAuthorizationGuard: a guard to protect your routes based on the Ory Keto permissions
8+
9+
## Install
10+
11+
```sh
12+
npm install @getlarge/keto-client-wrapper
13+
```
14+
15+
## Usage
16+
17+
Import the module in your app:
18+
19+
```ts
20+
import {
21+
OryRelationshipsModule,
22+
OryPermissionsModule,
23+
} from '@getlarge/keto-client-wrapper';
24+
import { Module } from '@nestjs/common';
25+
26+
@Module({
27+
imports: [
28+
OryRelationshipsModule.forRoot({
29+
basePath: 'http://localhost:4467',
30+
accessToken: 'my-access-token',
31+
}),
32+
OryPermissionsModule.forRootAsync({
33+
useFactory: () => ({
34+
baseUrl: 'http://localhost:4466',
35+
}),
36+
}),
37+
],
38+
})
39+
40+
```
41+
42+
Inject the service in your provider:
43+
44+
```ts
45+
import { OryRelationshipsService } from '@getlarge/keto-client-wrapper';
46+
import { Injectable } from '@nestjs/common';
47+
48+
@Injectable()
49+
export class YourService {
50+
constructor(private readonly oryRelationshipsService: OryRelationshipsService) {}
51+
}
52+
53+
```
54+
55+
Use the Guard to protect your routes:
56+
57+
```ts
58+
import { OryAuthorizationGuard, OryPermissionChecks } from '@getlarge/keto-client-wrapper';
59+
import {
60+
RelationTupleBuilder,
61+
} from '@getlarge/keto-relations-parser';
62+
import { Controller, Get, Logger, UseGuards } from '@nestjs/common';
63+
64+
@Controller()
65+
export class YourController {
66+
67+
@OryPermissionChecks((ctx) => {
68+
const req = ctx.switchToHttp().getRequest();
69+
const currentUserId = req.headers['x-current-user-id'] as string;
70+
const resourceId = req.params.id;
71+
return new RelationTupleBuilder()
72+
.subject('User', currentUserId)
73+
.isIn('owners')
74+
.of('Toy', resourceId)
75+
.toString();
76+
})
77+
@UseGuards(
78+
OryAuthorizationGuard({
79+
postCheck(relationTuple, isPermitted) {
80+
Logger.log('relationTuple', relationTuple);
81+
Logger.log('isPermitted', isPermitted);
82+
},
83+
})
84+
)
85+
@Get()
86+
getArticles() {
87+
return 'Articles';
88+
}
89+
}
90+
```
91+
92+
## Development
93+
94+
### Building
695

796
Run `nx build keto-client-wrapper` to build the library.
897

9-
## Running unit tests
98+
### Running unit tests
1099

11100
Run `nx test keto-client-wrapper` to execute the unit tests via [Jest](https://jestjs.io).
101+
```

‎packages/keto-client-wrapper/test/app.controller.mock.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
import { Controller, Get, Logger, Param, UseGuards } from '@nestjs/common';
2+
import { RelationTupleBuilder } from '@getlarge/keto-relations-parser';
23

34
import { ExampleService } from './app.service.mock';
45
import { OryAuthorizationGuard } from '../src/lib/ory-authorization.guard';
56
import { OryPermissionChecks } from '../src/lib/ory-permission-checks.decorator';
6-
import { RelationTupleBuilder } from '@getlarge/keto-relations-parser';
77

88
@Controller('Example')
99
export class ExampleController {

‎packages/keto-relations-parser/README.md‎

Lines changed: 109 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,117 @@
11
# keto-relations-parser
22

3-
This library was generated with [Nx](https://nx.dev).
3+
This library can parse a string representation of a Relation tuple to an object structure in typescript.
44

5-
## Building
5+
Relation tuples are used to evaluate permissions in "Zanzibar: Google's Consistent, Global Authorization System".
6+
7+
The BNF of a valid Relation tuple is as follows:
8+
9+
```bnf
10+
<relation-tuple> ::= <object>'#'relation'@'<subject> | <object>'#'relation'@('<subject>')'
11+
<object> ::= namespace':'object_id
12+
<subject> ::= subject_id | <subject_set>
13+
<subject_set> ::= <object>'#'relation
14+
```
15+
16+
## Examples of valid strings
17+
18+
```text
19+
Project:123#owners@User:321
20+
Project:123#editors@Group:admin#members
21+
Group:admin#members@321
22+
```
23+
24+
Which can be verbalized as :
25+
26+
```text
27+
User:123 is owner of Project:123
28+
members of Group:admin are editors of Project:123
29+
321 is member of Group:admin
30+
```
31+
32+
Which can be parsed to the following object structure:
33+
34+
```json
35+
{
36+
"namespace": "Project",
37+
"objecy": "123",
38+
"relation": "owners",
39+
"subject": {
40+
"namespace": "User",
41+
"object": "321"
42+
}
43+
}
44+
```
45+
46+
```json
47+
{
48+
"namespace": "Project",
49+
"id": "123",
50+
"relation": "editors",
51+
"subject": {
52+
"namespace": "Group",
53+
"object": "admin",
54+
"relation": "members"
55+
}
56+
}
57+
```
58+
59+
```json
60+
{
61+
"namespace": "Group",
62+
"id": "admin",
63+
"relation": "members",
64+
"subject": "321"
65+
}
66+
```
67+
68+
## Install
69+
70+
```sh
71+
npm install @getlarge/keto-relations-parser
72+
```
73+
74+
## Usage
75+
76+
Parse a string to a RelationTuple object:
77+
78+
```ts
79+
import { RelationTupleBuilder } from '@getlarge/keto-relations-parser';
80+
81+
const relationTuple = RelationTupleBuilder.fromString(
82+
'Project:123#owners@User:321'
83+
);
84+
```
85+
86+
Parse a relation tuple object to a string:
87+
88+
```ts
89+
import { RelationTuple } from '@getlarge/keto-relations-parser';
90+
91+
const relationTuple = new RelationTuple('Project', '123', 'owners', {
92+
namespace: 'User',
93+
object: '321',
94+
}).toString();
95+
```
96+
97+
Create a relation tuple using Fluent API:
98+
99+
```ts
100+
import { RelationTupleBuilder } from '@getlarge/keto-relations-parser';
101+
102+
new RelationTupleBuilder()
103+
.subject('User', '321')
104+
.isIn('owners')
105+
.of('Project', '321')
106+
.toString();
107+
```
108+
109+
## Development
110+
111+
### Building
6112

7113
Run `nx build keto-relations-parser` to build the library.
8114

9-
## Running unit tests
115+
### Running unit tests
10116

11117
Run `nx test keto-relations-parser` to execute the unit tests via [Jest](https://jestjs.io).

0 commit comments

Comments
 (0)