🧠 Tired of bloated ACLs? Meet scode-acl: A minimal, schema-driven, token-friendly access control system

Diyor Umarkulov — Sat, 02 Aug 2025 09:02:57 +0000

“Permissions shouldn't feel like building a nuclear reactor.”

— Every developer buried in JSON access trees

🔥 What's the problem?

In every project with users, roles, and permissions, you eventually hit something like this:

{
  "user": {
    "profile": {
      "read": true,
      "edit": false
    },
    "settings": {
      "change": true
    }
  },
  "order": {
    "delivery": {
      "cancel": true
    }
  }
}

😵‍💫 Massive, nested JSON

🤯 Redundant data (false/null/undefined)

🧩 Pain to store in JWTs, sessions, or URLs

🧨 Breaks when schema changes

🚀 Enter `scode-acl`

scode-acl (Structured Compressed ACL) is a schema-driven, ultra-compact access control tool built with TypeScript. It compresses permission data into string-encoded indexes like "0 3 7", verifiable by schema hash.

🛡 Core ideas:

✅ Schema → dot paths → compressed string
✅ Only stores true permissions
✅ Validates schema with crc32 or sha256
✅ Works great in JWTs, cookies, URLs, mobile apps
✅ Full access check API

⚙️ Flat Mode Example

import { createFlatSCode } from "scode-acl";

const schema = {
  user: {
    profile: ["read", "update"],
    settings: ["change"],
  },
  order: {
    delivery: ["cancel"],
  },
};

const access = {
  user: {
    profile: { read: true },
    settings: { change: true },
  },
  order: {
    delivery: { cancel: true },
  },
};

const formatter = createFlatSCode(schema);
const { access: accessString, schemaHash } = formatter.encodeAccess(access);

console.log(accessString); // → "0 3 5"

🔍 Parse access string

formatter.parseAccess(accessString, schemaHash);
// → ['user.profile.read', 'user.settings.change', 'order.delivery.cancel']

✅ Check a permission

formatter.hasAccess("user.profile.read", accessString);
// → true

⚡ Performance Comparison

Format

Encode Time

Size (30+ permissions)

JSON

~8ms

~300 bytes

scode-acl

~1.2ms

~16–28 bytes

It’s basically JWT-safe and sessionStorage-ready.

🔌 Use Cases

✅ JWT tokens — fits easily in payload
✅ GraphQL/REST auth guards
✅ Admin panels — cleaner than boolean spaghetti
✅ Mobile/web apps — tiny access footprint
✅ Firebase custom claims / access tokens

🔮 Why is it useful?

Only true permissions are stored
Schema hash ensures backward compatibility
Tiny strings — easier to debug than full JSON
Supports Flat and Nested encoding
100% TypeScript — type-safe, fast, and portable

🛠 Install

npm install scode-acl

🛣 Roadmap

Wildcard permissions (user.profile.*)
Role groups (admin, viewer)
GUI schema editor (Web playground)
Schema → TS type generator

🔗 Links

🧠 GitHub Repo
📦 NPM Package
🤝 Maintainer: @diyor-dev on LinkedIn

🧠 Final thoughts

Most ACL systems are heavy, bloated, or overcomplicated.

scode-acl is a minimalistic alternative designed to be:

🧩 Small enough to fit in a token.

🔍 Clear enough to read as a dot path.

🧠 Smart enough to validate itself.

If you're building systems that deal with auth, access control, roles, or modular UIs — try scode-acl.

Use it, fork it, improve it.

And if you’ve been burned by ACL complexity before —

you’ll probably find this very refreshing.

DEV Community: Diyor Umarkulov