diff --git a/README.md b/README.md index 2d0a50c5..73c6f0bf 100644 --- a/README.md +++ b/README.md @@ -2,27 +2,28 @@ ANTLR Grammar for the OpenFGA DSL and parser from and to the OpenFGA JSON Syntax -[![Go Reference](https://pkg.go.dev/badge/github.com/openfga/language.svg)](https://pkg.go.dev/github.com/openfga/language/pkg/go) -[![Release](https://img.shields.io/github/v/release/openfga/language?sort=semver&color=green)](https://github.com/openfga/language/releases) +[![@openfga/syntax-transformer on npm](https://img.shields.io/npm/v/%40openfga%2Fsyntax-transformer/beta?label=%40openfga%2Fsyntax-transformer&style=flat-square)](https://www.npmjs.com/package/@openfga/syntax-transformer) +[![GitHub Release](https://img.shields.io/github/v/release/openfga/language?include_prereleases&filter=pkg%2Fgo%2Fv*&label=go%20release)](https://github.com/openfga/language/tree/main/pkg/go) +[![openfga-language on Maven Central](https://img.shields.io/maven-central/v/dev.openfga/openfga-language?style=flat-square&label=maven-central)](https://central.sonatype.com/artifact/dev.openfga/openfga-language) + [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE) [![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fopenfga%2Flanguage.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fopenfga%2Flanguage?ref=badge_shield) [![Join our community](https://img.shields.io/badge/slack-cncf_%23openfga-40abb8.svg?logo=slack)](https://openfga.dev/community) [![Twitter](https://img.shields.io/twitter/follow/openfga?color=%23179CF0&logo=twitter&style=flat-square "@openfga on Twitter")](https://twitter.com/openfga) ## Table of Contents + - [About OpenFGA](#about) - [Resources](#resources) - [Packages](#packages) - [About This Repo](#about-this-repo) -- [Installation](#installation) -- [Usage](#usage) - [CLI](#cli) - [Community Parsers](#community-parsers) - [Contributing](#contributing) - [License](#license) - ## About + [OpenFGA](https://openfga.dev) is an open source Fine-Grained Authorization solution inspired by [Google's Zanzibar paper](https://research.google/pubs/pub48190/). It was created by the FGA team at [Auth0](https://auth0.com) based on [Auth0 Fine-Grained Authorization (FGA)](https://fga.dev), available under [a permissive license (Apache-2)](https://github.com/openfga/rfcs/blob/main/LICENSE) and welcomes community contributions. OpenFGA is designed to make it easy for application builders to model their permission layer, and to add and integrate fine-grained authorization into their applications. OpenFGA’s design is optimized for reliability and low latency at a high scale. @@ -38,105 +39,31 @@ OpenFGA is designed to make it easy for application builders to model their perm ## Packages -| Packages | Package Manager | -| -------- | --------------- | -| JS | [![@openfga/syntax-transformer on npm](https://img.shields.io/npm/v/@openfga/syntax-transformer.svg?label=@openfga/syntax-transformer&style=flat-square)](https://www.npmjs.com/package/@openfga/syntax-transformer) | -| Go | [![OpenFGA Language (Go) on GitHub](https://img.shields.io/github/v/release/openfga/language/pkg/go?label=openfga-language&style=flat-square)](https://github.com/openfga/language/tree/main/pkg/go) | -| Java | [![openfga-language on Maven Central](https://img.shields.io/maven-central/v/dev.openfga/openfga-language?style=flat-square&label=openfga-language)](https://central.sonatype.com/artifact/dev.openfga/openfga-language) | +| Packages | Package Manager | Docs | +| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | +| JS | [![@openfga/syntax-transformer on npm](https://img.shields.io/npm/v/%40openfga%2Fsyntax-transformer/beta?label=%40openfga%2Fsyntax-transformer&style=flat-square)](https://www.npmjs.com/package/@openfga/syntax-transformer) | [README](/pkg/js/README.md) | +| Go | [![GitHub Release](https://img.shields.io/github/v/release/openfga/language?include_prereleases&filter=pkg%2Fgo%2Fv*&label=openfga-language)](https://github.com/openfga/language/tree/main/pkg/go) | [README](/pkg/go/README.md) | +| Java | [![openfga-language on Maven Central](https://img.shields.io/maven-central/v/dev.openfga/openfga-language?style=flat-square&label=openfga-language)](https://central.sonatype.com/artifact/dev.openfga/openfga-language) | [README](/pkg/java/README.md) | ## About This Repo + This repo contains everything needed to interact with the OpenFGA Authorization Models schema versions 1.1+, in multiple languages (currently, Go and JS are supported). -| Feature | Implemented in ANTLR | -|------------|----------------------| -| Basic DSL | ✅ | +| Feature | Implemented in ANTLR | +| ---------- | ------------------------------------------------------------------------ | +| Basic DSL | ✅ | | Nesting | ✅ (partial, see [#113](https://github.com/openfga/language/issues/113)) | -| Conditions | ✅ | - -| Feature | Go | JS | Java | -|-------------------------------------------------------|----------------------|--------------|-----------------------| -| Transformer from the DSL to JSON and from JSON to DSL | ✅ | ✅ | ✅ | -| Syntactic Model Validations | ✅ | ✅ | ✅ | -| Schema 1.0 | ❌ | ❌ (supported in [v0.1.6](https://www.npmjs.com/package/@openfga/syntax-transformer/v/0.1.6) and below) | ❌ | -| Schema 1.1 | ✅ | ✅ (supported in [v0.2.0](https://www.npmjs.com/package/@openfga/syntax-transformer) and above) | ✅ | -| Schema 1.2 (Modular Models) | ✅ | ✅ | ✅ | -| Semantic Model Validations | ❌ (planned, see [#99](https://github.com/openfga/language/issues/99)) | ✅ | ✅ | -| Graphing & Utility Methods | ❌ (planned) | ❌ (planned) | ❌ (planned) | - - -## Installation -### Go -```bash -go get github.com/openfga/language/pkg/go -``` - -### Node -```bash -npm install @openfga/syntax-transformer -``` - -### Java -From [dev.openfga/openfga-language on MavenCentral](https://central.sonatype.com/artifact/dev.openfga/openfga-language) - -## Usage - -### Transformer - -#### Go -```go -import "github.com/openfga/language/pkg/go/transformer" - -dslString := `model - schema 1.1 -type user -type folder - relations - define viewer: [user]` - -// Transform from DSL to a JSON string -generatedJsonString, err := transformer.TransformDSLToJSONString(dslString) - -// Transform from a JSON string to DSL -generatedDsl, err := transformer.TransformJSONStringToDSL(generatedJsonString) -``` - -#### Node -```typescript -import { transformer } from "@openfga/syntax-transformer" - -let dslString = `model - schema 1.1 -type user -type folder - relations - define viewer: [user]`; - -// Transform from DSL to a JSON string -const generatedJsonString = transformer.transformDSLToJSONString(dslString) - -// Transform from a JSON string to DSL -const generatedDsl = transformer.transformJSONStringToDSL(generatedJsonString) -``` - -#### Java -```java -import dev.openfga.language.DslToJsonTransformer; -import dev.openfga.language.JsonToDslTransformer; - -var dslString = """model - schema 1.1 -type user -type folder - relations - define viewer: [user]"""; - -// Transform from DSL to a JSON string -var generatedJsonString = new DslToJsonTransformer().transform(dslString); - -// Transform from a JSON string to DSL -var generatedDsl = new JsonToDslTransformer().transform(generatedJsonString); -``` - +| Conditions | ✅ | + +| Feature | Go | JS | Java | +| ----------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------ | +| Transformer from the DSL to JSON and from JSON to DSL | ✅ | ✅ | ✅ | +| Syntactic Model Validations | ✅ | ✅ | ✅ | +| Schema 1.0 | ❌ | ❌ (supported in [v0.1.6](https://www.npmjs.com/package/@openfga/syntax-transformer/v/0.1.6) and below) | ❌ | +| Schema 1.1 | ✅ | ✅ (supported in [v0.2.0](https://www.npmjs.com/package/@openfga/syntax-transformer) and above) | ✅ | +| Schema 1.2 (Modular Models) | ✅ | ✅ | ✅ | +| Semantic Model Validations | ❌ (planned, see [#99](https://github.com/openfga/language/issues/99)) | ✅ | ✅ | +| Graphing & Utility Methods | ❌ (planned) | ❌ (planned) | ❌ (planned) | ## CLI @@ -145,19 +72,19 @@ Use the [FGA CLI](https://github.com/openfga/cli) ## Community Parsers | Repo | License | Maintainers | Language | Schema v1.0 | Schema v1.1 | Package Managers | Other Links | -|------------------------------------------------------------------------------|------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------|-------------------------------------------|-----------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------| -| [openfga language (syntax-transformer)](https://github.com/openfga/language) | [Apache-2.0](https://github.com/openfga/language/blob/main/LICENSE) | [@openfga](https://github.com/orgs/openfga/people) | ANTLR (Go and Typescript implementations) | <[0.1.5](https://www.npmjs.com/package/@openfga/syntax-transformer/v/0.1.5) | Yes (v0.0.8+) | [![npm:@openfga/syntax-transformer](https://img.shields.io/npm/v/@openfga/syntax-transformer.svg?style=flat)](https://www.npmjs.com/package/@openfga/syntax-transformer) - ![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/openfga/language?label=go) | | +| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | +| [openfga language (syntax-transformer)](https://github.com/openfga/language) | [Apache-2.0](https://github.com/openfga/language/blob/main/LICENSE) | [@openfga](https://github.com/orgs/openfga/people) | ANTLR (Go and Typescript implementations) | <[0.1.5](https://www.npmjs.com/package/@openfga/syntax-transformer/v/0.1.5) | Yes (v0.0.8+) | [![npm:@openfga/syntax-transformer](https://img.shields.io/npm/v/@openfga/syntax-transformer.svg?style=flat)](https://www.npmjs.com/package/@openfga/syntax-transformer) - ![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/openfga/language?label=go) | | | [openfga-dsl-parser](https://github.com/maxmindlin/openfga-dsl-parser) | [Apache-2.0](https://github.com/maxmindlin/openfga-dsl-parser/blob/master/LICENSE) | [@maxmindlin](https://github.com/maxmindlin) - [@dblclik](https://github.com/dblclik) | Rust | Yes | No | [![crates:openfga-dsl-parser](https://img.shields.io/crates/v/openfga-dsl-parser.svg?style=flat)](https://crates.io/crates/openfga-dsl-parser)[![pypi:openfga-dsl-parser-python](https://img.shields.io/pypi/v/openfga-dsl-parser-python.svg?style=flat)](https://pypi.org/project/openfga-dsl-parser-python/) | [WASM](https://github.com/dblclik/openfga-dsl-parser-wasm) - [Python](https://github.com/maxmindlin/openfga-dsl-parser-python) | | [openfga-rs](https://github.com/iammathew/openfga-rs) | [Apache-2.0](https://github.com/iammathew/openfga-rs/blob/main/LICENSE.md) | [@iammathew](https://github.com/iammathew) | Rust | Yes | No | | | | [openfga-dsl-parser](https://github.com/craigpastro/openfga-dsl-parser) | [Apache-2.0](https://github.com/craigpastro/openfga-dsl-parser/blob/main/LICENSE) | [@craigpastro](https://github.com/craigpastro) | ANTLR & Go | Yes | Partial (requires self). [Supports nesting](https://github.com/openfga/syntax-transformer/issues/34) | ![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/craigpastro/openfga-dsl-parser?label=go) | | ## Community Wrapper + | Repo | License | Maintainers | Language | Schema v1.0 | Schema v1.1 | Package Managers | Other Links | -|-----------------------------------------------------------------------|-------------------------------------------------------------------------|----------------------------------------------------|------------|-------------|-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------| +| --------------------------------------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------- | ---------- | ----------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | [fga cli](https://github.com/openfga/cli) | [Apache-2.0](https://github.com/openfga/cli/blob/main/LICENSE) | [@openfga](https://github.com/orgs/openfga/people) | Go | No | Yes | ![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/openfga/cli?label=go) | | | [fga-transformer-cli](https://github.com/ozee-io/fga-transformer-cli) | [MIT](https://github.com/ozee-io/fga-transformer-cli/blob/main/LICENSE) | [@ozee-io](https://github.com/orgs/ozee-io/people) | Javascript | Yes | Yes | [![npm:@openfga/syntax-transformer](https://img.shields.io/npm/v/@ozee-io/fga-transformer-cli.svg?style=flat)](https://www.npmjs.com/package/@ozee-io/fga-transformer-cli) | | - ## Contributing See [CONTRIBUTING](https://github.com/openfga/.github/blob/main/CONTRIBUTING.md). @@ -168,4 +95,4 @@ See [CONTRIBUTING](https://github.com/openfga/.github/blob/main/CONTRIBUTING.md) ## License -This project is licensed under the Apache-2.0 license. See the [LICENSE](https://github.com/openfga/cli/blob/main/LICENSE) file for more info. +This project is licensed under the Apache-2.0 license. See the [LICENSE](https://github.com/openfga/language/blob/main/LICENSE) file for more info. diff --git a/pkg/go/README.md b/pkg/go/README.md new file mode 100644 index 00000000..2b9f6628 --- /dev/null +++ b/pkg/go/README.md @@ -0,0 +1,130 @@ +# OpenFGA Language - GoLang + +GoLang implementation of ANTLR Grammar for the OpenFGA DSL and parser from and to the OpenFGA JSON Syntax + +[![Go Reference](https://pkg.go.dev/badge/github.com/openfga/language.svg)](https://pkg.go.dev/github.com/openfga/language/pkg/go) +[![GitHub Release](https://img.shields.io/github/v/release/openfga/language?include_prereleases&filter=pkg%2Fgo%2Fv*&label=openfga-language)](https://github.com/openfga/language/tree/main/pkg/go) + +## Installation + +```bash +go get github.com/openfga/language/pkg/go +``` + +## Usage + +### Transformer + +```go +import "github.com/openfga/language/pkg/go/transformer" + +... + +dslString := `model + schema 1.1 +type user +type folder + relations + define viewer: [user]` + +// Transform from DSL syntax to the OpenFGA Authorization Model Protobuf format +generatedProto, err := transformer.TransformDSLToProto(dslString) + +// Transform from DSL to a JSON string +generatedJsonString, err := transformer.TransformDSLToJSONString(dslString) + +// Transform from a JSON string to DSL +generatedDsl, err := transformer.TransformJSONStringToDSL(generatedJsonString) +``` + +### Transform Mod to JSON + +```go +import "github.com/openfga/language/pkg/go/transformer" + +... + +modFileContents := `schema: "1.2" +contents: + - core.fga + - board.fga + - wiki.fga` + +// Transform from fga.mod to a JSON object for parsing +jsonModFile, err := transformer.TransformModFile(modFileContents) +``` + +### Transform Modules To Model + +```go +import "github.com/openfga/language/pkg/go/transformer" + +... + +// Transform an array of modules, and their contents, into a singular model +model, err := transformer.TransformModuleFilesToModel([]transformer.ModuleFile{ + { + Name: "core.fga", + Contents: `module core + type user`, + }, + { + Name: "board.fga", + Contents: `module core + type board`, + }, + { + Name: "wiki.fga", + Contents: `module core + type wiki`, + }, + + }, "1.2") + + +jsonString, _ := json.MarshalIndent(model, "", " ") + +/* +{ + "schema_version": "1.2", + "type_definitions": [ + { + "type": "user", + "metadata": { + "module": "core", + "source_info": { + "file": "core.fga" + } + } + }, + { + "type": "board", + "metadata": { + "module": "core", + "source_info": { + "file": "board.fga" + } + } + }, + { + "type": "wiki", + "metadata": { + "module": "core", + "source_info": { + "file": "wiki.fga" + } + } + } + ] +} +*/ + +``` + +### Validation + +Not yet implemented, but the [feature is in our issue backlog](https://github.com/openfga/language/issues/99). + +## License + +This project is licensed under the Apache-2.0 license. See the [LICENSE](https://github.com/openfga/language/blob/main/LICENSE) file for more info. diff --git a/pkg/java/README.md b/pkg/java/README.md new file mode 100644 index 00000000..8aac09c2 --- /dev/null +++ b/pkg/java/README.md @@ -0,0 +1,96 @@ +# OpenFGA Language - Java + +Java implementation of ANTLR Grammar for the OpenFGA DSL and parser from and to the OpenFGA JSON Syntax + +[![openfga-language on Maven Central](https://img.shields.io/maven-central/v/dev.openfga/openfga-language?style=flat-square&label=openfga-language)](https://central.sonatype.com/artifact/dev.openfga/openfga-language) + +## Installation + +From [dev.openfga/openfga-language on MavenCentral](https://central.sonatype.com/artifact/dev.openfga/openfga-language) + +## Usage + +### Transformer + +```java +import dev.openfga.language.DslToJsonTransformer; +import dev.openfga.language.JsonToDslTransformer; + +... + +var dslString = """ +model + schema 1.2 +type user +type folder + relations + define viewer: [user] +"""; + +// Transform from DSL to a JSON string +var generatedJsonString = new DslToJsonTransformer().transform(dslString); + +// Transform from a JSON string to DSL +var generatedDsl = new JsonToDslTransformer().transform(generatedJsonString); + +// Parses DSL returning results DSL without throwing +var result = new DslToJsonTransformer().parseDsl(dslString); +``` + +### Transform Mod to JSON + +```java +import dev.openfga.language.FgaModTransformer; + +... + +var modFileContents = """ +schema: "1.2" +contents: + - core.fga + - board.fga + - wiki.fga +"""; + +// Parse fga.mod to a FgaModFile object +var mod = new FgaModTransformer(modFileContents).parse(); + +// Parse fga.mod to JSON string +var jsonMod = new FgaModTransformer(modFileContents).transform(); +``` + +### Transform set of Modules To Model + +Not yet implemented, but the [enchancement is in our issue backlog](https://github.com/openfga/language/issues/279). + +### Validation + +```java +import dev.openfga.language.validation.ModelValidator; +import dev.openfga.language.errors.DslErrorsException; + +... + +var dslString = """ +model + schema 1.2 +type user +type folder + relations + define viewer: [user] +"""; + +try { + ModelValidator.validateDsl(dslString); +} catch (DslErrorsException e) { + // Handle generated errors + return e.getErrors(); +} catch (IOException e) { + throw new RuntimeException(e); +} + +``` + +## License + +This project is licensed under the Apache-2.0 license. See the [LICENSE](https://github.com/openfga/language/blob/main/LICENSE) file for more info. diff --git a/pkg/js/README.md b/pkg/js/README.md new file mode 100644 index 00000000..b907c71b --- /dev/null +++ b/pkg/js/README.md @@ -0,0 +1,150 @@ +# OpenFGA Language - JS + +Javascript implementation of ANTLR Grammar for the OpenFGA DSL and parser from and to the OpenFGA JSON Syntax + +[![@openfga/syntax-transformer](https://img.shields.io/npm/v/%40openfga%2Fsyntax-transformer/beta?label=%40openfga%2Fsyntax-transformer&style=flat-square)](https://www.npmjs.com/package/@openfga/syntax-transformer) + +## Installation + +```bash +npm install @openfga/syntax-transformer +``` + +## Usage + +### Transformer + +Example transform DSL model to JSON, and from JSON to DSL. + +```typescript +import { transformer } from "@openfga/syntax-transformer"; + +let dslString = `model + schema 1.1 +type user +type folder + relations + define viewer: [user]`; + +// Transform from DSL model to a JSON object +const generatedJsonObject = transformer.transformDSLToJSONObject(dslString); + +// Transform from DSL to a JSON string +const generatedJsonString = transformer.transformDSLToJSONString(dslString); + +// Transform from a JSON string to DSL +const generatedDsl = transformer.transformJSONStringToDSL(generatedJsonString); +``` + +### Transform Mod File to JSON + +```typescript +import { transformer } from "@openfga/syntax-transformer"; + +... + +const modFileContents = `schema: "1.2" +contents: + - core.fga + - board.fga + - wiki.fga` + +// Transform from fga.mod to an object +const jsonModFile = transformer.TransformModFile(modFileContents) +``` + +### Transform set of Modules To Model + +```typescript +import { transformer } from "@openfga/syntax-transformer"; + +... + +const files: transformer.ModuleFile[] = []; +files.push({ + name: "core.fga", + contents: `module core + type user` + }, + { + name: "board.fga", + contents: `module core + type board` + }, + { + name: "wiki.fga", + contents: `module core + type wiki` + } +); + +// Compile module files into a complete model +const jsonModel = transformer.transformModuleFilesToModel(files, "1.2"); + +/* +{ + "schema_version": "1.2", + "type_definitions": [ + { + "type": "user", + "metadata": { + "module": "core", + "source_info": { + "file": "core.fga" + } + } + }, + { + "type": "board", + "metadata": { + "module": "core", + "source_info": { + "file": "board.fga" + } + } + }, + { + "type": "wiki", + "metadata": { + "module": "core", + "source_info": { + "file": "wiki.fga" + } + } + } + ] +} +*/ + +``` + +### Validation + +```typescript +import { errors, validator } from "@openfga/syntax-transformer"; + +... + +let dslString = `model + schema 1.2 +type user +type folder + relations + define viewer: [user]`; + +// Attempt validation of model +try { + validator.validateDSL(dslString); +} catch (err) { + if (err instanceof errors.BaseMultiError) { + // Handle generated errors + } else { + console.error("Unhandled Exception: " + err); + } +} + +``` + +## License + +This project is licensed under the Apache-2.0 license. See the [LICENSE](https://github.com/openfga/language/blob/main/LICENSE) file for more info. diff --git a/pkg/js/package.json b/pkg/js/package.json index 35b6d562..e4625043 100644 --- a/pkg/js/package.json +++ b/pkg/js/package.json @@ -11,8 +11,8 @@ "build": "npm run build:ts", "build:npx": "tsc --build tsconfig.json", "clean": "rm -r dist/", - "prepublishOnly": "npm run build && cp ../../README.md . && cp ../../LICENSE .", - "postpublish": "rm -f README.md LICENSE", + "prepublishOnly": "npm run build && cp ../../LICENSE .", + "postpublish": "rm -f LICENSE", "test": "jest --config ./jest.config.js", "typecheck": "tsc --skipLibCheck", "lint": "eslint . -c .eslintrc.js --ext .ts",