fgalgo

日本語版はこちら (Japanese Version)

fgalgo is a Node.js tool that automatically generates OpenFGA Authorization Models and Relationship Tuples. It reads user attributes and device information from Excel files and Matter specification XML files, then generates Authorization Models and Relationship Tuples compatible with OpenFGA.

Key Features

• Automatic Generation

  • Automatic import of user and device information from Excel files
  • Parsing Matter specification XML files to generate device types and command sets
  • Automatic generation of Authorization Models (.fga)
  • Automatic generation of Relationship Tuples
  • Automatic deployment to OpenFGA server
  • Interactive device permission configuration

• Automatic Update

  • Fetch and save Authorization Models and Relationship Tuples from OpenFGA server
  • Statistical analysis and summary display of existing data (user count, device count, group count, permission relationships, etc.)
  • Interactive CLI for managing users, devices, and groups
  • Natural language-based permission changes using LLM (Gemini API)
  • Automatic application of changes to OpenFGA

Requirements

• Node.js (v18 or higher recommended)
• python3
• OpenFGA CLI (fga command)
• OpenFGA server

Setup

1. Clone the Repository

git clone <repository-url>
cd fgalgo

2. Install Dependencies

npm install

3. Configure Environment Variables

Copy .env.sample to create a .env file and configure OpenFGA connection settings:

cp .env.sample .env

Edit the .env file:

FGA_API_URL=your-openfga-api-url
FGA_STORE_ID=your-store-id
FGA_API_TOKEN=your-api-token
GEMINI_API_KEY=your-gemini-api-key

4. Prepare Input Files

Place the following files in the appropriate directories:

Device-related

• matter_xml/ - Matter specification XML files

Configuration files

• user_groups.xlsx - User group definitions
• user_attributes.xlsx - User attributes
• device_attributes.xlsx - Device attributes

Examples of configuration file formats are shown below:

User Groups (user_groups.xlsx)

Format

No.	Field	Description	Type
1	id	ID	int
2	uid	Unique group ID	string
3	name	Human-readable name	string
4	parent	Parent hierarchy group name	string / null

Example

id	uid	name	parent
1	teacher	Teacher Group
2	doctor	PhD Student Group	teacher

User Attributes (user_attributes.xlsx)

Format

No.	Field	Description	Type
1	id	ID	int
2	uid	Unique user ID	string
3	name	Human-readable name	string
4	group	Affiliated groups	array of string / null
5	room	Affiliated rooms	array of string / null

Example

id	uid	name	group	room
1	tanaka	Taro Tanaka	teacher	room101, room102
2	sato	Hanako Sato	doctor	room102

Device Attributes (device_attributes.xlsx)

Format

No.	Field	Description	Type
1	id	ID	int
2	uid	Unique device ID	string
3	name	Human-readable name	string
4	type	Device type	string
5	room	Affiliated rooms	array of string / null

Example

uid	name	type	room
light101	Room 101 Light	onofflightswitch	room101
lock102	Room 102 Smart Lock	doorlock	room102

Usage

Basic Execution

node main.js

Select create (automatic generation) or update (automatic update) when prompted.

Running Create Mode

Create mode generates new Authorization Models and Relationship Tuples from Excel files and Matter specification XML files, then deploys them to OpenFGA.

Required Input Files

Before running create mode, prepare the following files:

User-related (Excel files)

• user_groups.xlsx - User group definitions
• user_attributes.xlsx - User attributes

Device-related

• device_attributes.xlsx - Device attributes
• matter_xml/ - Matter specification XML files
• file/json/matter/devicetype.json - Device type definitions (generated by Python script)

Execution Flow

1. User Information Processing

   • Load user groups and user attributes from Excel files
   • Generate Authorization Model for users
   • Generate Relationship Tuples for users

2. Device Information Processing

   • Load Matter device types from JSON
   • Load device attributes from Excel
   • Interactive device configuration (permissions, actions)
   • Generate Authorization Model for devices
   • Generate Relationship Tuples for devices

3. Deploy to OpenFGA

   • Send integrated Authorization Model to OpenFGA server
   • Upload all Relationship Tuples

Running Update Mode

Update mode allows you to fetch existing data from OpenFGA and interactively manage and update it.

Execution Flow

1. Data Retrieval and Storage

   • Fetch current Authorization Model from OpenFGA server
   • Fetch current Relationship Tuples from OpenFGA server (with pagination support)
   • Save retrieved data to ./file/update/model.fga and ./file/update/tuple.json

2. Statistical Analysis and Display

   • Automatically analyze statistics for users, devices, groups, and rooms
   • Display counts of each entity, permission relationships, and active relations
   • Display aggregated information by device type

3. Interactive Mode

   • Select the item to manage from the main menu (users/devices/groups)
   • Enter permission change requests in natural language
   • LLM analyzes the request and generates an execution plan
   • Review and approve the generated plan
   • Automatically apply changes to OpenFGA

LLM-Powered Permission Changes

Update mode uses Gemini API to execute permission changes from natural language.

Usage Examples

Natural language request examples:
- "Grant Tanaka access to the door lock in room 101"
- "Remove all device permissions for Sato"
- "Grant admin permissions to the doctor group for all devices in room102"

The LLM automatically performs the following:

1. Parse and structure the request
2. Verify consistency with current data
3. Generate an execution plan for necessary changes
4. Generate updated Authorization Model and Relationship Tuples

Project Structure

fgalgo/
├── main.js                 # Main entry point
├── package.json           
├── .env                   # Environment variables
├── src/                   # Source code
│   ├── create/           # Automatic generation features
│   │   ├── user/         # User-related processing
│   │   ├── device/       # Device-related processing
│   │   ├── export/       # FGA export processing
│   │   └── util/         # Utility functions
│   └── update/           # Automatic update features
│       ├── api/          # OpenFGA API client
│       ├── cli/          # Interactive CLI
│       └── llm/          # LLM integration (Gemini)
├── file/                 # Input and template files
│   ├── template/         # EJS templates
│   ├── model/            # FGA model files (for auto-generation)
│   ├── update/           # Files for automatic update
│   │   ├── model.fga     # Fetched Authorization Model
│   │   ├── tuple.json    # Fetched Relationship Tuples
│   │   ├── update_model.fga    # Updated Model (LLM-generated)
│   │   └── update_tuple.json   # Updated Tuples (LLM-generated)
│   └── json/             # JSON data files
├── matter_xml/           # Matter specification XML files
└── python/               # Python auxiliary scripts

Dependencies

• @openfga/sdk - OpenFGA SDK
• exceljs - Excel file processing
• xml2js - XML parsing
• ejs - Template engine
• inquirer - Interactive CLI
• dotenv - Environment variable management

Development

Python Scripts

Generate device type JSON from Matter XML specification files:

cd python
python parse-matter-devices-xml-to-json.py

Saved to file/json/matter