Forem: Herdi Tr.

Introducing Guantr: A Type-Safe Authorization Library for JavaScript/TypeScript

Herdi Tr. — Wed, 09 Apr 2025 15:08:00 +0000

Handling permissions and access control is a fundamental part of building almost any web application. Deciding who can do what with which resource can quickly become complex. While working on one of my own projects, I found myself needing a solution that was not only flexible but also highly type-safe, integrating seamlessly with my TypeScript codebase.

Existing solutions didn't quite fit the bill – some felt too restrictive, others lacked the compile-time safety I was looking for, and some involved deploying entirely separate services which felt like overkill for my needs at the time. This led me down the path of building a custom authorization logic layer directly within that application.

After running and refining this core logic in production, I realized it might be useful to others facing similar challenges. So, I decided to extract it, polish it up, add features like customizable storage, and release it as an open-source library: Guantr.

What is Guantr?

Guantr is an embedded authorization library for JavaScript and TypeScript. Its primary goal is to provide a flexible and developer-friendly way to manage permissions directly within your application codebase, with a strong emphasis on type safety.

It's not a standalone service like some other authorization systems; instead, you integrate it as a library, define your rules using familiar JS/TS constructs, and check permissions where needed.

Key Features

Here are some of the core ideas behind Guantr:

1. TypeScript First with `GuantrMeta`

Guantr shines when used with TypeScript. You can define your entire authorization model – resources, actions, data shapes, and context structure – using the GuantrMeta type.

import type { GuantrMeta } from 'guantr';

// Define your models and context shape
interface PostModel { id: string; authorId: string; status: string; }
interface UserContext { userId: string | null; roles: string[]; }

// Define the Meta type
type AppMeta = GuantrMeta<
  { // Resource Map
    post: { action: 'read' | 'edit' | 'delete'; model: PostModel; };
    // ... other resources
  },
  // Context Shape
  UserContext 
>;

// Use it during initialization
const guantr = await createGuantr<AppMeta>({ /* ... options ... */ });

This provides compile-time safety and autocompletion when defining rules and checking permissions, helping to catch errors early.

2. Flexible Condition System

Rules can include conditions for fine-grained control (ABAC/ReBAC patterns). Guantr uses a straightforward array syntax [operator, operand] for these conditions.

await guantr.setRules<AppMeta>(async (allow, deny) => {
  // Allow reading any post
  allow('read', 'post');

  // Allow editing a post IF its authorId matches the current user's ID
  allow('edit', ['post', { 
    authorId: ['eq', '$ctx.userId'] // Check resource property against context
  }]);

  // Deny deleting posts that are 'published'
  deny('delete', ['post', {
    status: ['eq', 'published'] // Check resource property
  }]);
});

3. Context Integration (`getContext` & `$ctx`)

Dynamic information, like the current user's ID or roles, can be injected via an asynchronous getContext function during initialization. This context is then accessible within rule conditions using the $ctx. prefix.

const guantr = await createGuantr<AppMeta>({
  getContext: async (): Promise<UserContext> => {
    const user = await getCurrentUser(); // Fetch user data per request
    return { userId: user?.id ?? null, roles: user?.roles ?? [] };
  }
});

// Rule using context (from previous example):
// allow('edit', ['post', { authorId: ['eq', '$ctx.userId'] }]);

4. Pluggable Storage

While Guantr includes a simple InMemoryStorage by default, it defines a Storage interface. This allows you to implement custom adapters to persist and query rules from different backends like PostgreSQL, MySQL, Redis, MongoDB, etc., making it suitable for various architectures. Examples are included in the documentation.

Who is Guantr For?

Guantr is likely a good fit if:

You are working primarily within the JavaScript/TypeScript ecosystem.
You prefer embedding authorization logic within your application rather than using a separate service.
Type safety is a high priority for your team.
You need fine-grained control based on resource attributes, user context, or relationships (ABAC/ReBAC).

Getting Started

You can install it via npm (or your preferred package manager):

npm install guantr

Here's a minimal example:

import { createGuantr } from 'guantr';

async function main() {
  // 1. Initialize Guantr
  const guantr = await createGuantr();

  // 2. Set some rules
  await guantr.setRules((allow, deny) => {
    allow('read', 'article'); // Anyone can read articles
    allow('edit', ['article', { status: ['eq', 'draft'] }]); // Can edit only if status is 'draft'
  });

  // 3. Check permissions
  const draftArticle = { id: 1, status: 'draft' };
  const publishedArticle = { id: 2, status: 'published' };

  const canRead = await guantr.can('read', 'article'); // true
  const canEditDraft = await guantr.can('edit', ['article', draftArticle]); // true
  const canEditPublished = await guantr.can('edit', ['article', publishedArticle]); // false

  console.log({ canRead, canEditDraft, canEditPublished });
}

main();

Learn More

This is just a brief introduction. You can find comprehensive guides, API references, and more examples in the official documentation: guantr.hrdtr.dev

The core logic powering Guantr has proven useful in a real-world application, and my hope is that releasing it as an open-source library might help others who need a similar blend of flexibility and type safety for their authorization needs.

Feedback, suggestions, and contributions are highly appreciated! Check out the GitHub repository if you're interested.

Thanks for reading!

Integrate NuxtJS with Appwrite

Herdi Tr. — Tue, 31 Aug 2021 05:35:13 +0000

What is Appwrite?

Appwrite is an end-to-end backend server that is aiming to abstract the complexity of common, complex, and repetitive tasks required for building a modern app.

Appwrite provides you with a set of APIs, tools, and a management console UI to help you build your apps a lot faster and in a much more secure way. Between Appwrite different services, you can find user authentication and account management, user preferences, database and storage persistence, cloud functions, localization, image manipulation, scheduled background tasks, and more.

Preparation

Before starting make sure you have installed appwrite on the server and appwrite is running fine there, if you haven't installed it please open the appwrite documentation and install it on your server.

By the way the setup process is very easy.

Getting Started

Lets create a new NuxtJS project

yarn create nuxt-app <project-name>

or using npm:

npm init nuxt-app <project-name>

After the the package successfully installed, add appwrite module for NuxtJS

$ cd <project-name>
$ yarn add nuxt-appwrite

or using npm:

$ cd <project-name>
$ npm i nuxt-appwrite <project-name>

Next, add nuxt-appwrite to the modules section of in nuxt.config.js

export default {
  ...
  modules: ['nuxt-appwrite']
  ...
}

At this point, make sure we have an active project in appwrite, if not, please login to your appwrite console and create a new project, then go to project settings and copy the value from project id field.

Next, add appwrite object inside nuxt.config.js export and fill it with some options

export default {
  ...
  modules: ['nuxt-appwrite'],
  appwrite: {
    endpoint: 'https://appwrite.example.com/v1', // appwrite endpoint
    project: '60046530a120d', // project id
  }
  ...

Great! We have successfully setup the Appwrite Web SDK in NuxtJS

From here, we can use this.$appwrite to access the SDK from clients side methods in NuxtJS (e.g. mounted()).

For example, we can fetch database document inside vue component like this:

{
  ...
  mounted() {
    try {
      const res = this.$appwrite.database.getDocument(collectionID, documentID)
      this.document = res
    } catch (err) {
      console.log(err.message)
    }
  },
  ...
}

Server Side User Action

To maximize the capabilities of NuxtJS, $appwrite also accessible from NuxtJS context. So we can access the SDK from server side too (e.g.asyncData()).

However, when doing SDK calls in your users scope from the server, it is not possible right away, since the HTTP-only cookie used for authentication is saved in the user's browser. That's why the Appwrite Web SDK allows to use JWT for authentication.

There are additional steps that must be taken so that our NuxtJS server instance knows who we are (the logged in user). that way, the server can get the same access rights according to the user who is currently logged in.

Below is an example code to set JWT using the APIs available in nuxt-appwrite module (do it directly after the user has successfully logged in):

this.$appwrite.account
  .createJWT()
  .then((response) => {
    console.log(response)
    this.$appwrite.utils.setJWT(response.jwt)
  })
  .catch((error) => {
    console.log(error)
  })

Once the JWT is set, we can use the user-scoped action on the Nuxt process.server context, asyncData and nuxtServerInit.

Don't forget to remove the JWT after the user logs out

this.$appwrite
  .account.deleteSessions('current')
  .then(() => {
    this.$appwrite.utils.removeJWT()
  }, function (error) {
    console.log(error);
  });

By the way Appwrite has a public community on discord, you can join and find out more about Appwrite and if you run into any problems or difficulties people there are always there to help.

Forem: Herdi Tr.

Introducing Guantr: A Type-Safe Authorization Library for JavaScript/TypeScript

What is Guantr?

Key Features

1. TypeScript First with GuantrMeta

2. Flexible Condition System

3. Context Integration (getContext & $ctx)

4. Pluggable Storage

Who is Guantr For?

Getting Started

Learn More

Integrate NuxtJS with Appwrite

What is Appwrite?

Preparation

Getting Started

Server Side User Action

1. TypeScript First with `GuantrMeta`

3. Context Integration (`getContext` & `$ctx`)