keto-relations-parser

This library can parse a string representation of a Relation tuple to an object structure in typescript. It is a fork of the relation-tuple-parser library which uses Regular Expressions to parse the string instead of Antlr4 and provides a fluent API to create a Relation tuple.

Relation tuples are used to evaluate permissions in "Zanzibar: Google's Consistent, Global Authorization System".

The BNF of a valid Relation tuple is as follows:

<relation-tuple> ::= <object>'#'relation'@'<subject> | <object>'#'relation'@('<subject>')'
<object> ::= namespace':'object_id
<subject> ::= subject_id | <subject_set>
<subject_set> ::= <object>'#'relation

Examples of valid strings

Project:123#owners@User:321
Project:123#editors@Group:admin#members
Group:admin#members@321

Which can be verbalized as :

User:123 is owner of Project:123
members of Group:admin are editors of Project:123
321 is member of Group:admin

Which can be parsed to the following object structure:

{
  "namespace": "Project",
  "objecy": "123",
  "relation": "owners",
  "subject": {
    "namespace": "User",
    "object": "321"
  }
}

{
  "namespace": "Project",
  "id": "123",
  "relation": "editors",
  "subject": {
    "namespace": "Group",
    "object": "admin",
    "relation": "members"
  }
}

{
  "namespace": "Group",
  "id": "admin",
  "relation": "members",
  "subject": "321"
}

Install

npm install @getlarge/keto-relations-parser

Usage

Parse a string to a RelationTuple object:

import { RelationTupleBuilder } from '@getlarge/keto-relations-parser';

const relationTuple = RelationTupleBuilder.fromString(
  'Project:123#owners@User:321'
);

Parse a relation tuple object to a string:

import { RelationTuple } from '@getlarge/keto-relations-parser';

const relationTuple = new RelationTuple('Project', '123', 'owners', {
  namespace: 'User',
  object: '321',
}).toString();

Create a relation tuple using Fluent API:

import { RelationTupleBuilder } from '@getlarge/keto-relations-parser';

new RelationTupleBuilder()
  .subject('User', '321')
  .isIn('owners')
  .of('Project', '321')
  .toString();

Development

Building

Run nx build keto-relations-parser to build the library.

Running unit tests

Run nx test keto-relations-parser to execute the unit tests via Jest.