DEV Community: Hamidreza Mahdavipanah

A Practical Specification for Roles, Permissions, and Policy Decisions

Hamidreza Mahdavipanah — Sun, 17 May 2026 12:33:19 +0000

The full specification is available here: Authorization Model Specification.

Authorization logic often starts simple.

At first, a role like admin, editor, or viewer is enough. Then the product grows. You add organizations, projects, machine clients, service accounts, field-level rules, exceptions, audit logs, and suddenly the question "can this principal do this action?" is answered differently in different parts of the codebase.

This specification is my attempt to make that question explicit, portable, and easy to evaluate.

The goal is not to define authentication, token issuance, identity provisioning, or transport security. Those are separate concerns. This spec focuses only on authorization decisions: how roles, permissions, scopes, and policy evaluation should work together.

The Core Idea

The model is built around a small chain:

Principal -> Role -> Permission -> allow | deny

A principal can be a human user, a service account, or a machine-to-machine client. A role is a named bundle of permission statements, such as auditor, editor, or billing-admin.

Roles are not magical. Their names do not grant authority by themselves. A role only matters because of the permission statements it contains, and a principal only receives authority through an explicit binding:

(principal, role, scope)

This is important because it keeps the model auditable. If someone has access, there should be a concrete binding and a concrete permission statement that explains why.

The Design Principles

The specification is based on five principles:

Default-deny: if nothing explicitly allows an action, the answer is deny.

Deny-overrides: if both an allow and a deny match the same request, the deny wins.

Explicit over implicit: authority is never inferred from role names, group names, or conventions.

Decision and enforcement separation: application code should ask a Policy Decision Point (PDP) for a decision. It should not spread authorization rules across controllers, services, and handlers.

Auditability: decisions should be loggable with enough context to reconstruct what happened.

These principles make the model predictable. There is no hidden privilege, no role-name guessing, and no ambiguous conflict resolution.

Permission Strings

Permission statements are serialized as compact strings:

<organization>:<service>/<resource>[:<field>[:<resource_id>]]/<effect>/<action>

For example:

acme:api/suppliers/allow/update

This means: in the acme organization, for the api service, allow updating suppliers.

The format also supports field-level and instance-level rules:

acme:api/contacts:email/allow/read
acme:api/suppliers:*:12345/deny/read

The first statement allows reading only the email field of contacts. The second denies reading supplier 12345.

Wildcards are supported too:

acme:api/suppliers/allow/*
acme:api/suppliers/deny/delete

Together, these allow every action on suppliers except deletion.

The string format is intentionally compact enough to be transported in places like JWT claims, while still being readable for operators and auditors.

How Evaluation Works

The evaluator receives a request:

(principal, action, resource_uri)

Then it evaluates the principal's effective permission set in three steps.

First, it keeps only the permission statements that match the request. A segment matches if it is exactly equal to the request segment or if it is *.

Second, if any matching statement has effect = deny, the result is deny.

Third, if at least one matching statement has effect = allow and no deny matched, the result is allow. Otherwise, the result is deny.

In pseudocode:

def evaluate(request, permissions):
    applicable = [p for p in permissions if matches(p, request)]

    if any(p.effect == "deny" for p in applicable):
        return Decision.DENY

    if any(p.effect == "allow" for p in applicable):
        return Decision.ALLOW

    return Decision.DENY

One important detail: the evaluator is specificity-agnostic. A specific deny does not beat a wildcard allow because it is more specific. It wins because all denies override all allows.

For example:

acme:api/suppliers/allow/read
acme:api/suppliers:*:12345/deny/read

Reading suppliers is generally allowed, but reading supplier 12345 is denied.

What This Spec Is For

This specification is useful for teams building a Policy Decision Point, integrating a Policy Enforcement Point, or simply trying to make authorization rules easier to audit.

It gives you:

a portable permission string format
clear role and binding semantics
default-deny behavior
deny-overrides conflict handling
a small evaluation algorithm
decision logging requirements

The main benefit is consistency. Instead of each service inventing its own interpretation of roles and permissions, services can ask the same kind of question and receive the same kind of answer.

Authorization should be boring, predictable, and explainable. That is what this spec is designed to support.

You can read the complete spec, including the grammar, validation rules, examples, and versioning notes, at mahdavipanah.github.io/authorization-model.

The Book “Atomic Habits” - My Insights and Key Takeaways

Hamidreza Mahdavipanah — Thu, 20 Nov 2025 11:20:19 +0000

The Power of Small, Consistent Steps

If there’s one lesson that hit me the hardest from James Clear, it’s this:
Big changes don’t come from big actions. They come from tiny ones done consistently.

People obsess over massive goals, perfect plans, and sudden motivation. But in reality, life rewards the person who quietly improves a little bit every single day. One percent. That’s it. Repeat long enough, and the compound effect takes over.

Your current reality — your fitness, skills, career, relationships — is basically the accumulated result of your daily habits. When the inputs are solid, the outputs eventually align.

And the real question isn’t:
.
.
.

Read the complete post on my Substack: https://hamidrezam.substack.com/p/atomic-habits

Javascript's Tricky "This" Keyword and Why Arrow Functions Matter

Hamidreza Mahdavipanah — Tue, 18 Mar 2025 14:28:41 +0000

JavaScript's flexibility and dynamic nature make it a powerful language, but certain features—like the this keyword—can lead to confusion, especially within nested functions. Understanding how this behaves is crucial for writing predictable and maintainable code.

The `this` Keyword in JavaScript

In JavaScript, the value of this is determined by how a function is invoked, not where it's defined. When a regular function is called as a method of an object (obj.method()), this refers to that object. However, when a function is invoked standalone (func()), this typically refers to the global object (in non-strict mode) or is undefined (in strict mode) (MDN documentation).

Common Pitfall: Losing the Context

Consider the following example:

class MyClass {
  constructor() {
    this.factor = 2;
  }

  methodA(value) {
    return value * this.factor;
  }

  methodB() {
    return [1, 2, 3, 4].map(function (value) {
      const newValue = value + 1;
      return this.methodA(newValue); // TypeError: Cannot read properties of undefined (reading 'methodA')
    });
  }
}

In this example, the callback passed to map() is a regular function, causing this to be undefined inside it. This results in a runtime error.

Arrow Functions: A Concise Solution

Arrow functions provide a concise syntax and lexically bind this, meaning they inherit this from their surrounding scope (Google JS Style Guide):

class MyClass {
  constructor() {
    this.factor = 2;
  }

  methodA(value) {
    return value * this.factor;
  }

  methodB() {
    return [1, 2, 3, 4].map((value) => {
      const newValue = value + 1;
      return this.methodA(newValue);
    });
  }
}

With arrow functions, the context of this remains bound to the instance of MyClass, preventing the earlier error.

Best Practices

To avoid confusion and potential errors with this, consider these guidelines:

Prefer Arrow Functions for Nested Functions: Arrow functions simplify the scoping of this in nested functions.
Avoid Function Expressions for Callbacks: Regular functions can lead to unexpected bindings. Use arrow functions for callbacks.
Explicit Binding with bind: If using regular functions, explicitly bind this using .bind(this) (MDN bind).

By understanding the behavior of this and utilizing arrow functions appropriately, you can write more predictable and maintainable JavaScript code.

Introducing keyv-upstash: Seamless Key-Value Storage for Serverless Redis

Hamidreza Mahdavipanah — Tue, 10 Dec 2024 17:27:11 +0000

Github: https://github.com/mahdavipanah/keyv-upstash

keyv-upstash is a storage adapter for Keyv that connects it to Upstash Redis, a serverless Redis platform. With this adapter, you get a simple, efficient, and flexible solution for key-value storage in serverless applications.

What is Keyv?

Keyv is a versatile key-value storage library that supports multiple backends through adapters. It provides:

TTL-based Expiry: Ideal for caching or persistent storage.
Namespace Support: Avoids key collisions in shared environments.
Extensibility: Easy to build custom modules or add features like compression.

Keyv works with many adapters, such as Redis, SQLite, MongoDB, and now, keyv-upstash for Upstash Redis.

Why `keyv-upstash`?

keyv-upstash extends Keyv's capabilities by integrating it with Upstash Redis, offering:

Serverless Compatibility: Upstash Redis works without managing connections, scaling automatically, perfect for serverless apps.
Flexible: Compatible with Keyv’s ecosystem and supports third-party extensions.
Cache Layering: Combine with Cacheable for multi-layered caching.
No Vendor Lock-In: Is fully compatible with serverless-redis-http so you can setup your own serverless Redis and use this adapter with it.

Getting Started

Follow these steps to integrate keyv-upstash:

1. Install Keyv and `keyv-upstash`

Install Keyv and the Upstash adapter:

npm install keyv keyv-upstash

Optional: Install Cacheable for layered caching:

npm install cacheable

2. Set Up `keyv-upstash`

Make sure you have a Redis database created in Upstash. Here’s how to use keyv-upstash in your project:

Basic Usage

import Keyv from 'keyv';
import { KeyvUpstash } from 'keyv-upstash';

const keyv = new Keyv({
  store: new KeyvUpstash({
    url: 'your-upstash-redis-url',
    token: 'your-upstash-redis-token',
  }),
});

// Set a key-value pair
await keyv.set('foo', 'bar');

// Retrieve the value
const value = await keyv.get('foo');
console.log(value); // 'bar'

Using Namespaces

Namespaces prevent key collisions and allow scoped clearing:

const keyv = new Keyv({
  store: new KeyvUpstash({
    url: 'your-upstash-redis-url',
    token: 'your-upstash-redis-token',
    namespace: 'my-namespace',
  }),
});

await keyv.set('foo', 'bar'); // Stored as 'my-namespace::foo'

Cache Layering with Cacheable

Combine keyv-upstash with Cacheable for multi-layer caching:

import { Cacheable } from 'cacheable';

const redisStore = new KeyvUpstash({
  url: 'your-upstash-redis-url',
  token: 'your-upstash-redis-token',
});

const cache = new Cacheable({
  primary: new Map(), // Fast in-memory caching
  secondary: redisStore, // Persistent Redis caching
});

await cache.set('foo', 'bar', { ttl: 1000 }); // Stores in both layers
const value = await cache.get('foo'); // Fast lookup from memory or Redis
console.log(value); // 'bar'

Advanced Features

Batch Operations

Improve performance with setMany and getMany:

await keyv.setMany([
  { key: 'key1', value: 'value1' },
  { key: 'key2', value: 'value2' },
]);

const values = await keyv.getMany(['key1', 'key2']);
console.log(values); // ['value1', 'value2']

Custom Configuration

Customize your setup with options like defaultTtl, keyPrefixSeparator, and clearBatchSize.

Fast and Simple NestJS App Deployment on Vercel

Hamidreza Mahdavipanah — Tue, 26 Nov 2024 19:10:38 +0000

This article is also available on my blog: https://hamidreza.tech/nestjs-on-vercel.

This guide is beneficial if you're using Express adapter. For NestJS applications utilizing the Fastify adapter, these links may be helpful:

https://fastify.dev/docs/latest/Guides/Serverless/#vercel

https://github.com/vercel/examples/tree/main/starter/fastify

🚀 You can access the complete source code discussed in this article at this GitHub repository: https://github.com/mahdavipanah/nestjs-on-vercel

Vercel's Support for Express Apps

Vercel offers a convenient feature for deploying your Express app by:

Exposing the Express app object in an API.
Defining a rewrite rule that directs all incoming traffic to this single API.

I followed Vercel’s official guide for deploying Express to deploy NestJS by similarly exposing NestJS’s underlying Express app object.

Step 1 - create a NestJS app

Skip this step if you already have a NestJS app set up.

Install NestJS and create a new app:

nest new my-app

Step 2 - Install Necessary NPM Packages

npm install express @nestjs/platform-express
npm install -D @types/express

Step 3 - Create `src/AppFactory.ts` file

This file serves as a single module that manages all necessary NestJS app bootstrapping and exports both the NestJS app and its underlying Express app object.

Create a file named AppFactory.ts inside the src directory in your project’s root:

import { ExpressAdapter } from '@nestjs/platform-express';
import { NestFactory } from '@nestjs/core';
import express, { Request, Response } from 'express';
import { Express } from 'express';
import { INestApplication } from '@nestjs/common';
import { AppModule } from './app.module.js';

export class AppFactory {
  static create(): {
    appPromise: Promise<INestApplication<any>>;
    expressApp: Express;
  } {
    const expressApp = express();
    const adapter = new ExpressAdapter(expressApp);
    const appPromise = NestFactory.create(AppModule, adapter);

    appPromise
      .then((app) => {
        // You can add all required app configurations here

        /**
         * Enable cross-origin resource sharing (CORS) to allow resources to be requested from another domain.
         * @see {@link https://docs.nestjs.com/security/cors}
         */
        app.enableCors({
          exposedHeaders: '*',
        });

        app.init();
      })
      .catch((err) => {
        throw err;
      });

    // IMPORTANT This express application-level middleware makes sure the NestJS app is fully initialized
    expressApp.use((req: Request, res: Response, next) => {
      appPromise
        .then(async (app) => {
          await app.init();
          next();
        })
        .catch((err) => next(err));
    });

    return { appPromise, expressApp };
  }
}

Step 4 - Modify `src/main.ts` File

By default, NestJS has a src/main.ts file that serves as the entry point of the application, including all configuration and bootstrapping. Modify this file to move everything to the AppFactory.ts file, keeping only the invocation of the listen method:

import { AppFactory } from './AppFactory.js';

async function bootstrap() {
  const { appPromise } = AppFactory.create();
  const app = await appPromise;

  await app.listen(process.env.PORT ?? 3000);
}
bootstrap();

Step 5 - Add `api/index.ts` File

By default, the Vercel runtime builds and serves any function created within the /api directory of a project to Vercel (doc). Since Vercel understands and handles the Express app object, create a function inside this directory that exports the Express app object:

/**
 * This file exports Express instance for specifically for the deployment of the app on Vercel.
 */

import { AppFactory } from '../src/AppFactory.js';

export default AppFactory.create().expressApp;

Step 6 - Add `vercel.json` File

Create a file named vercel.json in the project’s root directory to configure Vercel. Here, define a rewrite rule for Vercel to use the Express app to serve all incoming traffic (doc).

You can also use a tsconfig.json file at the api directory to configure the Vercel’s TypeScript compiler. Most options are supported aside from "Path Mappings" and "Project References".

{
  "version": 2,
  "buildCommand": "npm run build",
  "outputDirectory": ".",
  "rewrites": [
    {
      "source": "/(.*)",
      "destination": "/api"
    }
  ]
}

Step 7 - Create a Project on Vercel

Congratulations 🎉! We are almost done. Now, create a git repository and push your source code to it. Then, go to your Vercel account, create a new project, and import the git repository. You can also use this article’s example GitHub repository.

Pitfalls of URL and URLSearchParams in JavaScript

Hamidreza Mahdavipanah — Fri, 22 Nov 2024 16:59:48 +0000

This article is also available on my blog: https://hamidreza.tech/pitfalls-of-url-and-urlsearchparams-in-nodejs

It All Started With a Bug

Working with URLs in JavaScript and Node.js should be straightforward, but a recent bug in our project led me down a rabbit hole of subtle quirks in the URL and URLSearchParams APIs. This post will explore these quirks, how they can cause problems in your code, and what you can do to avoid them.

The Problem: URL Handling with Axios

We encountered this issue while generating URLs and adding hash signatures to them. The query parameters weren’t consistently percent-encoded, leading to unexpected behavior and wrong hash signatures.

It became clear that the interaction between URL and URLSearchParams objects required extra care.

Pitfall #1: `URL.search` vs. `URLSearchParams.toString()`

The first surprise was the difference between URL.search and URLSearchParams.toString().

Use care when using .searchParams to modify the URL because, per the WHATWG specification, the URLSearchParams object uses different rules to determine which characters to percent-encode. For instance, the URL object will not percent-encode the ASCII tilde (~) character, while URLSearchParams will always encode it.

// Example 1
const url = new URL("https://example.com?param=foo bar");
console.log(url.search); // prints param=foo%20bar
console.log(url.searchParams.toString()); // prints ?param=foo+bar

// Example 2
const myURL = new URL('https://example.org/abc?foo=~bar');
console.log(myURL.search);  // prints ?foo=~bar
// Modify the URL via searchParams...
myURL.searchParams.sort();
console.log(myURL.search);  // prints ?foo=%7Ebar

In our project, we needed to explicitly reassign url.search = url.searchParams.toString() to ensure the query string was encoded consistently.

Pitfall #2: The Plus Sign Dilemma

Another gotcha is how URLSearchParams handles + characters. By default, URLSearchParams interprets + as a space, which may lead to data corruption when encoding binary data or Base64 strings.

const params = new URLSearchParams("bin=E+AXQB+A");
console.log(params.get("bin")); // "E AXQB A"

One solution is to use encodeURIComponent before appending values to URLSearchParams:

params.append("bin", encodeURIComponent("E+AXQB+A"));

More details are available in the MDN documentation.

Pitfall #3: `URLSearchParams.get` vs. `URLSearchParams.toString()`

Another subtlety arises when comparing the outputs of URLSearchParams.get and URLSearchParams.toString. For example:

const params = new URLSearchParams("?key=value&key=other");
console.log(params.get("key")); // "value" (first occurrence)
console.log(params.toString()); // "key=value&key=other" (all occurrences serialized)

In multi-valued scenarios, get returns only the first value, while toString serializes all.

The Fix in Our Codebase

In our project, we resolved the issue by explicitly reassigning the search property:

url.search = url.searchParams.toString();
url.searchParams.set(
  "hash",
  cryptography.createSha256HmacBase64UrlSafe(url.href, SECRET_KEY ?? "")
);

This ensured that all query parameters were properly encoded before adding the hash value.

Node.js `querystring` module

The WHATWG URLSearchParams interface and the querystring module have a similar purpose, but the purpose of the querystring module is more general, as it allows the customization of delimiter characters (& and =). On the other hand, URLSearchParams API is designed purely for URL query strings.

querystring is more performant than URLSearchParams but is not a standardized API. Use URLSearchParams when performance is not critical or when compatibility with browser code is desirable.

When using URLSearchParams unlike querystring module, duplicate keys in the form of array values are not allowed. Arrays are stringified using array.toString(), which simply joins all array elements with commas.

const params = new URLSearchParams({
  user: 'abc',
  query: ['first', 'second'],
});
console.log(params.getAll('query'));
// Prints [ 'first,second' ]
console.log(params.toString());
// Prints 'user=abc&query=first%2Csecond'

With querystring module, the query string 'foo=bar&abc=xyz&abc=123' is parsed into:

{
  "foo": "bar",
  "abc": ["xyz", "123"]
}

Takeaways

Be cautious of how URLSearchParams handles special characters (e.g. ~) and spaces. Use encodeURIComponent when necessary.
Understand the difference between URL.search, URLSearchParams.get, and URLSearchParams.toString to avoid unexpected behavior.
In Node.js use querystring module if you want to parse duplicate query parameter keys as an array.

Resolving MongoDB Error When Starting with Homebrew on macOS

Hamidreza Mahdavipanah — Thu, 21 Nov 2024 11:20:15 +0000

This article is also available on my blog: https://hamidreza.tech/mongodb-error-with-homebrew-on-macos

Introduction

While installing MongoDB Community Edition on my MacBook using Homebrew (official MongoDB doc), I encountered an issue: the mongodb-community service seemed to start successfully but was listed as error when I checked its status. If you're facing the same problem, here's a quick guide to help you fix it.

The Issue

After running:

brew services start mongodb-community

I received a confirmation message. However, checking the service status with:

brew services list

showed:

Name              Status  User Plist
mongodb-community error

The MongoDB log (/usr/local/var/log/mongodb/mongo.log) contained warnings:

Running as root user: "You are running this process as the root user, which is not recommended"
Termination signal received: "Received signal","attr":{"signal":15,"error":"Terminated: 15"}}

These indicated that MongoDB was running as the root user, which can cause permission issues and lead to the service being stopped.

The Solution

The main issue was incorrect ownership of the MongoDB data and log directories. Here's how to fix it:

Steps:

Stop the MongoDB Service:
```
brew services stop mongodb-community
```
Terminate Any Running MongoDB Processes:
```
pkill -f mongod
```

Change Ownership of MongoDB Directories:

sudo chown -R $(whoami) /usr/local/var/mongodb
sudo chown -R $(whoami) /usr/local/var/log/mongodb

Verify Directory Ownership:
```
ls -ld /usr/local/var/mongodb
ls -ld /usr/local/var/log/mongodb
```
Ensure your username is listed as the owner.
Start the MongoDB Service as Your User:
```
brew services start mongodb-community
```
Check the Service Status:
```
brew services list
```
The service should now show as started under your username.
Test the MongoDB Connection:
```
mongosh
```
You should successfully connect to the MongoDB shell.

Conclusion

By correcting the directory permissions and ensuring MongoDB runs under your user account (not as root), you can resolve the error when starting the mongodb-community service with Homebrew on macOS. Remember to avoid using sudo with brew commands to prevent permission conflicts.

Using @ and */ symbols inside JS multiline comments

Hamidreza Mahdavipanah — Fri, 12 Apr 2024 12:55:37 +0000

While documenting JavaScript code using JSDoc, I stumbled upon an annoying issue. My attempts to include the /* symbol in the example code within a multiline comment caused the entire comment block to break. This happens because */ is recognized as the ending tag for a multiline comment in JavaScript.

You can see the problem clearly in the blow code block!

/**
 * Checks whether two permission strings are semantically equal or not.
 *
 * @example
 * // returns true
 * equals('a/b/c/d/allow', 'a/b/c/*⁣/*/d/allow');
 *
 * @returns {boolean} True in case of equality and false otherwise.
*/
const equals = (first: string, second: string) => {
    // function's logic
    // ...

    return true; // or false
}

The solution is surprisingly simple: insert a Unicode invisible separator character between * and /. This character acts as a stealthy spacer, preventing the JavaScript interpreter from recognizing the sequence as the end of a comment. You can find and copy this invisible character here.

The same problem happens if you use the @ symbol to put a JSDoc code example of a decorator. Because the @ symbol has a special meaning for JSDoc, it leads to unintended changes in the rendered documentation. Consider this snippet:

/**
 * A NestJS handler decorator that defines an access permission constraint and enforces it.
 *
 * @example
 * `⁣`⁣`ts
 * // the request only needs to be authenticated and doesn't need any specific permissions
 * @RequiresAccess()
 * Class MyController {}
 * `⁣`⁣`
*/
export const RequiresAccess = Reflector.createDecorator<
  PermissionPathGen | PermissionPathGen[]
>({
  transform(value) {
    return value == undefined ? MUST_BE_AUTHENTICATED : value;
  },
});

Solving this is the same as the previous problem, you need to put an invisible separator before the @.