@alsania-io/acl

Sovereign object-level ACL for Alsania. Zero dependencies.

Principals (user/group/public) are granted numeric permission bits on resources. Roles are named bit sets. Enforcement is default-deny for non-public resources.

Extracted from AlsaniaMCP (EME Storage Router Phase 4, 2026-10-12). The model is reused verbatim — not forked — and the ResourceType is extended with namespace, storage, and secret.

Install

npm install @alsania-io/acl

Usage

import { Acl, PermBits } from "@alsania-io/acl";

const acl = new Acl();
const alice = { type: "user", id: "alice" } as const;

// Grant VIEW on a secret to alice.
acl.grantPermission(alice, { type: "secret", id: "MY_API_KEY" }, { permBits: PermBits.VIEW });

acl.checkPermission(alice, { type: "secret", id: "MY_API_KEY" }, PermBits.VIEW); // true

Model

• PermBits: NONE 0 · VIEW 1 · CALL 2 · EDIT 4 · ADMIN 8 (combine with |).
• ResourceType: mcpServer · tool · agent · prompt · namespace · storage · secret.
• Principals: { type: "user" | "group" | "public", id? }.
• A principal's effective bits = union of its own entry, its group entries (supplied at check time), and the public entry.
• checkPermission requires ALL bits in required (bitwise AND).

API

| Method | Purpose | |---|---| | defineRole(role) | Register a named bit set bound to a resource type | | grantPermission(principal, resource, opts) | Grant/update (idempotent) | | revokePermission(principal, resource) | Revoke (0 or 1 removed) | | effectiveBits(principal, resource, groupIds?) | Union of matching bits | | checkPermission(principal, resource, required, groupIds?) | Boolean check | | findAccessibleResources(principal, type, required?, groupIds?) | Query | | getPermissionsMap(principal, groupIds?) | resourceKey -> bits | | listResourcePermissions(resource) | Raw entries |

License

MIT — Imagined by Sigma. Powered by Echo.