acl-next 1.0.0

package/dist/index.js

@@ -0,0 +1,667 @@
+// src/middleware.ts
+var HttpError = class extends Error {
+  errorCode;
+  name = "HttpError";
+  constructor(errorCode, message) {
+    super(message);
+    this.errorCode = errorCode;
+  }
+};
+function aclMiddleware(acl, numPathComponents, userId, actions) {
+  return (req, res, next) => {
+    var _a, _b, _c;
+    let resolvedUserId;
+    if (typeof userId === "function") {
+      resolvedUserId = userId(req, res);
+    } else if (userId !== void 0) {
+      resolvedUserId = userId;
+    } else {
+      resolvedUserId = ((_a = req.session) == null ? void 0 : _a.userId) ?? ((_b = req.user) == null ? void 0 : _b.id);
+    }
+    if (resolvedUserId === void 0 || resolvedUserId === null) {
+      next(new HttpError(401, "User not authenticated"));
+      return;
+    }
+    const fullUrl = (req.originalUrl ?? req.url ?? "").split("?")[0] ?? "";
+    const resource = numPathComponents ? fullUrl.split("/").slice(0, numPathComponents + 1).join("/") : fullUrl;
+    const resolvedActions = actions ?? req.method.toLowerCase();
+    (_c = acl.logger) == null ? void 0 : _c.debug(`Requesting ${resolvedActions} on ${resource} by user ${resolvedUserId}`);
+    acl.isAllowed(resolvedUserId, resource, resolvedActions).then(
+      (allowed) => {
+        var _a2, _b2;
+        if (allowed) {
+          (_a2 = acl.logger) == null ? void 0 : _a2.debug(`Allowed ${resolvedActions} on ${resource} by user ${resolvedUserId}`);
+          next();
+        } else {
+          (_b2 = acl.logger) == null ? void 0 : _b2.debug(
+            `Not allowed ${resolvedActions} on ${resource} by user ${resolvedUserId}`
+          );
+          next(new HttpError(403, "Insufficient permissions to access resource"));
+        }
+      },
+      () => next(new Error("Error checking permissions to access resource"))
+    );
+  };
+}
+function aclErrorHandler(contentType) {
+  return (err, _req, res, next) => {
+    if (!(err instanceof HttpError) || !err.errorCode) {
+      next(err);
+      return;
+    }
+    const response = res.status(err.errorCode);
+    if (contentType === "json") {
+      response.json({ message: err.message });
+    } else if (contentType === "html") {
+      response.send(err.message);
+    } else {
+      response.end(err.message);
+    }
+  };
+}
+
+// src/acl.ts
+var DEFAULT_BUCKETS = {
+  meta: "meta",
+  parents: "parents",
+  permissions: "permissions",
+  resources: "resources",
+  roles: "roles",
+  users: "users"
+};
+var toArray = (value) => Array.isArray(value) ? value : [value];
+var union = (a, b) => [.../* @__PURE__ */ new Set([...a, ...b])];
+var allowsBucket = (resource) => `allows_${resource}`;
+var keyFromAllowsBucket = (bucket) => bucket.replace(/^allows_/, "");
+var Acl = class {
+  backend;
+  logger;
+  buckets;
+  constructor(backend, logger, options) {
+    this.backend = backend;
+    this.logger = logger;
+    this.buckets = { ...DEFAULT_BUCKETS, ...options == null ? void 0 : options.buckets };
+  }
+  /** Adds roles to a given user id. */
+  async addUserRoles(userId, roles) {
+    const transaction = this.backend.begin();
+    this.backend.add(transaction, this.buckets.meta, "users", userId);
+    this.backend.add(transaction, this.buckets.users, userId, roles);
+    for (const role of toArray(roles)) {
+      this.backend.add(transaction, this.buckets.roles, role, userId);
+    }
+    await this.backend.end(transaction);
+  }
+  /** Removes roles from a given user id. */
+  async removeUserRoles(userId, roles) {
+    const transaction = this.backend.begin();
+    this.backend.remove(transaction, this.buckets.users, userId, roles);
+    for (const role of toArray(roles)) {
+      this.backend.remove(transaction, this.buckets.roles, role, userId);
+    }
+    await this.backend.end(transaction);
+  }
+  /** Returns all the roles assigned to a given user id. */
+  userRoles(userId) {
+    return this.backend.get(this.buckets.users, userId);
+  }
+  /** Returns all users that have the given role. */
+  roleUsers(roleName) {
+    return this.backend.get(this.buckets.roles, roleName);
+  }
+  /** Returns whether the user has the given role. */
+  async hasRole(userId, role) {
+    const roles = await this.userRoles(userId);
+    return roles.includes(role);
+  }
+  /** Adds one or more parent roles to a role. */
+  async addRoleParents(role, parents) {
+    const transaction = this.backend.begin();
+    this.backend.add(transaction, this.buckets.meta, "roles", role);
+    this.backend.add(transaction, this.buckets.parents, role, parents);
+    await this.backend.end(transaction);
+  }
+  /** Removes parent role(s) from a role. Omit `parents` to remove all of them. */
+  async removeRoleParents(role, parents) {
+    const transaction = this.backend.begin();
+    if (parents !== void 0) {
+      this.backend.remove(transaction, this.buckets.parents, role, parents);
+    } else {
+      this.backend.del(transaction, this.buckets.parents, role);
+    }
+    await this.backend.end(transaction);
+  }
+  /** Removes a role from the system, including all its permissions. */
+  async removeRole(role) {
+    const resources = await this.backend.get(this.buckets.resources, role);
+    const transaction = this.backend.begin();
+    for (const resource of resources) {
+      this.backend.del(transaction, allowsBucket(resource), role);
+    }
+    this.backend.del(transaction, this.buckets.resources, role);
+    this.backend.del(transaction, this.buckets.parents, role);
+    this.backend.del(transaction, this.buckets.roles, role);
+    this.backend.remove(transaction, this.buckets.meta, "roles", role);
+    await this.backend.end(transaction);
+  }
+  /** Removes a resource from the system. */
+  async removeResource(resource) {
+    const roles = await this.backend.get(this.buckets.meta, "roles");
+    const transaction = this.backend.begin();
+    this.backend.del(transaction, allowsBucket(resource), roles);
+    for (const role of roles) {
+      this.backend.remove(transaction, this.buckets.resources, role, resource);
+    }
+    await this.backend.end(transaction);
+  }
+  async allow(roles, resources, permissions) {
+    if (resources === void 0) {
+      return this.allowEx(roles);
+    }
+    const rolesArr = toArray(roles);
+    const resourcesArr = toArray(resources);
+    const transaction = this.backend.begin();
+    this.backend.add(transaction, this.buckets.meta, "roles", rolesArr);
+    for (const resource of resourcesArr) {
+      for (const role of rolesArr) {
+        this.backend.add(
+          transaction,
+          allowsBucket(resource),
+          role,
+          permissions
+        );
+      }
+    }
+    for (const role of rolesArr) {
+      this.backend.add(transaction, this.buckets.resources, role, resourcesArr);
+    }
+    await this.backend.end(transaction);
+  }
+  /** Removes permissions from a role over resources. Omit `permissions` to remove all. */
+  removeAllow(role, resources, permissions) {
+    return this.removePermissions(
+      role,
+      toArray(resources),
+      permissions !== void 0 ? toArray(permissions) : null
+    );
+  }
+  /**
+   * Removes permissions from a role over the given resources. When
+   * `permissions` is null the resource is fully revoked for the role.
+   *
+   * Note: loses atomicity when pruning emptied role/resource links.
+   */
+  async removePermissions(role, resources, permissions) {
+    const transaction = this.backend.begin();
+    for (const resource of resources) {
+      const bucket = allowsBucket(resource);
+      if (permissions) {
+        this.backend.remove(transaction, bucket, role, permissions);
+      } else {
+        this.backend.del(transaction, bucket, role);
+        this.backend.remove(transaction, this.buckets.resources, role, resource);
+      }
+    }
+    await this.backend.end(transaction);
+    const cleanup = this.backend.begin();
+    await Promise.all(
+      resources.map(async (resource) => {
+        const remaining = await this.backend.get(allowsBucket(resource), role);
+        if (remaining.length === 0) {
+          this.backend.remove(cleanup, this.buckets.resources, role, resource);
+        }
+      })
+    );
+    await this.backend.end(cleanup);
+  }
+  /**
+   * Returns, per resource, the permissions a user has. Uses the backend's
+   * `unions` optimization when available.
+   */
+  async allowedPermissions(userId, resources) {
+    if (!userId) {
+      return {};
+    }
+    if (this.backend.unions) {
+      return this.optimizedAllowedPermissions(userId, resources);
+    }
+    const resourcesArr = toArray(resources);
+    const roles = await this.userRoles(userId);
+    const result = {};
+    await Promise.all(
+      resourcesArr.map(async (resource) => {
+        result[resource] = await this.resourcePermissions(roles, resource);
+      })
+    );
+    return result;
+  }
+  /** `allowedPermissions` variant using the backend `unions` bulk query. */
+  async optimizedAllowedPermissions(userId, resources) {
+    if (!userId) {
+      return {};
+    }
+    const resourcesArr = toArray(resources);
+    const roles = await this.allUserRoles(userId);
+    const buckets = resourcesArr.map(allowsBucket);
+    const response = roles.length === 0 ? Object.fromEntries(buckets.map((bucket) => [bucket, []])) : (
+      // biome-ignore lint/style/noNonNullAssertion: guarded by the `this.backend.unions` caller
+      await this.backend.unions(buckets, roles)
+    );
+    const result = {};
+    for (const bucket of Object.keys(response)) {
+      result[keyFromAllowsBucket(bucket)] = response[bucket] ?? [];
+    }
+    return result;
+  }
+  /** Checks if a user is allowed all of the given permissions on a resource. */
+  async isAllowed(userId, resource, permissions) {
+    const roles = await this.backend.get(this.buckets.users, userId);
+    if (roles.length) {
+      return this.areAnyRolesAllowed(roles, resource, permissions);
+    }
+    return false;
+  }
+  /** Returns true if any of the roles has all of the given permissions. */
+  areAnyRolesAllowed(roles, resource, permissions) {
+    const rolesArr = toArray(roles);
+    const permsArr = toArray(permissions);
+    if (rolesArr.length === 0) {
+      return Promise.resolve(false);
+    }
+    return this.checkPermissions(rolesArr, resource, permsArr);
+  }
+  whatResources(roles, permissions) {
+    const rolesArr = toArray(roles);
+    const perms = permissions === void 0 ? void 0 : toArray(permissions);
+    return this.permittedResources(rolesArr, perms);
+  }
+  /** Backing implementation for {@link whatResources}. */
+  async permittedResources(roles, permissions) {
+    const rolesArr = toArray(roles);
+    const resources = await this.rolesResources(rolesArr);
+    if (permissions === void 0) {
+      const result2 = {};
+      await Promise.all(
+        resources.map(async (resource) => {
+          result2[resource] = await this.resourcePermissions(rolesArr, resource);
+        })
+      );
+      return result2;
+    }
+    const result = [];
+    await Promise.all(
+      resources.map(async (resource) => {
+        const p = await this.resourcePermissions(rolesArr, resource);
+        if (permissions.some((perm) => p.includes(perm))) {
+          result.push(resource);
+        }
+      })
+    );
+    return result;
+  }
+  /**
+   * Express-style middleware that authorizes the current request against this
+   * Acl. See {@link aclMiddleware} for parameter semantics. Pair with
+   * {@link aclErrorHandler} to render the resulting 401/403 errors.
+   */
+  middleware(numPathComponents, userId, actions) {
+    return aclMiddleware(this, numPathComponents, userId, actions);
+  }
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+  /** Compact array form of {@link allow}. */
+  async allowEx(rules) {
+    const demuxed = [];
+    for (const rule of toArray(rules)) {
+      for (const a of rule.allows) {
+        demuxed.push({ roles: rule.roles, resources: a.resources, permissions: a.permissions });
+      }
+    }
+    for (const d of demuxed) {
+      await this.allow(d.roles, d.resources, d.permissions);
+    }
+  }
+  /** Direct parents of the given roles. */
+  rolesParents(roles) {
+    return this.backend.union(this.buckets.parents, roles);
+  }
+  /** All roles in the hierarchy, including the given roles. */
+  async allRoles(roleNames) {
+    const parents = await this.rolesParents(roleNames);
+    if (parents.length > 0) {
+      const parentRoles = await this.allRoles(parents);
+      return union(roleNames, parentRoles);
+    }
+    return roleNames;
+  }
+  /** All roles in the hierarchy of the given user. */
+  async allUserRoles(userId) {
+    const roles = await this.userRoles(userId);
+    if (roles && roles.length > 0) {
+      return this.allRoles(roles);
+    }
+    return [];
+  }
+  /** All resources reachable by the given roles (through the hierarchy). */
+  async rolesResources(roles) {
+    const allRoles = await this.allRoles(toArray(roles));
+    const result = [];
+    await Promise.all(
+      allRoles.map(async (role) => {
+        const resources = await this.backend.get(this.buckets.resources, role);
+        result.push(...resources);
+      })
+    );
+    return result;
+  }
+  /** Permissions the given roles (and their parents) have over a resource. */
+  async resourcePermissions(roles, resource) {
+    if (roles.length === 0) {
+      return [];
+    }
+    const resourcePermissions = await this.backend.union(allowsBucket(resource), roles);
+    const parents = await this.rolesParents(roles);
+    if (parents == null ? void 0 : parents.length) {
+      const morePermissions = await this.resourcePermissions(parents, resource);
+      return union(resourcePermissions, morePermissions);
+    }
+    return resourcePermissions;
+  }
+  /**
+   * Whether the roles (and their parents) satisfy all permissions on a resource.
+   *
+   * NOTE: does not handle circular role hierarchies.
+   */
+  async checkPermissions(roles, resource, permissions) {
+    const resourcePermissions = await this.backend.union(allowsBucket(resource), roles);
+    if (resourcePermissions.includes("*")) {
+      return true;
+    }
+    const remaining = permissions.filter((p) => !resourcePermissions.includes(p));
+    if (remaining.length === 0) {
+      return true;
+    }
+    const parents = await this.backend.union(this.buckets.parents, roles);
+    if (parents == null ? void 0 : parents.length) {
+      return this.checkPermissions(parents, resource, remaining);
+    }
+    return false;
+  }
+};
+
+// src/backends/memory.ts
+var toArray2 = (value) => Array.isArray(value) ? value : [value];
+var toStr = (value) => `${value}`;
+var MemoryBackend = class {
+  buckets = /* @__PURE__ */ new Map();
+  begin() {
+    return [];
+  }
+  async end(transaction) {
+    for (const mutation of transaction) {
+      mutation();
+    }
+  }
+  async clean() {
+    this.buckets.clear();
+  }
+  async get(bucket, key) {
+    var _a;
+    const values = (_a = this.buckets.get(bucket)) == null ? void 0 : _a.get(toStr(key));
+    return values ? [...values] : [];
+  }
+  async unions(buckets, keys) {
+    const keyStrs = keys.map(toStr);
+    const result = {};
+    for (const bucket of buckets) {
+      const store = this.buckets.get(bucket);
+      if (!store) {
+        result[bucket] = [];
+        continue;
+      }
+      const union2 = /* @__PURE__ */ new Set();
+      for (const key of keyStrs) {
+        for (const value of store.get(key) ?? []) {
+          union2.add(value);
+        }
+      }
+      result[bucket] = [...union2];
+    }
+    return result;
+  }
+  async union(bucket, keys) {
+    let store = this.buckets.get(bucket);
+    if (!store) {
+      for (const name of this.buckets.keys()) {
+        if (new RegExp(`^${name}$`).test(bucket)) {
+          store = this.buckets.get(name);
+          break;
+        }
+      }
+    }
+    if (!store) {
+      return [];
+    }
+    const union2 = /* @__PURE__ */ new Set();
+    for (const key of keys) {
+      for (const value of store.get(toStr(key)) ?? []) {
+        union2.add(value);
+      }
+    }
+    return [...union2];
+  }
+  add(transaction, bucket, key, values) {
+    const keyStr = toStr(key);
+    const valueStrs = toArray2(values).map(toStr);
+    transaction.push(() => {
+      let store = this.buckets.get(bucket);
+      if (!store) {
+        store = /* @__PURE__ */ new Map();
+        this.buckets.set(bucket, store);
+      }
+      const existing = store.get(keyStr);
+      store.set(
+        keyStr,
+        existing ? [.../* @__PURE__ */ new Set([...valueStrs, ...existing])] : [...new Set(valueStrs)]
+      );
+    });
+  }
+  del(transaction, bucket, keys) {
+    const keyStrs = toArray2(keys).map(toStr);
+    transaction.push(() => {
+      const store = this.buckets.get(bucket);
+      if (!store) {
+        return;
+      }
+      for (const key of keyStrs) {
+        store.delete(key);
+      }
+    });
+  }
+  remove(transaction, bucket, key, values) {
+    const keyStr = toStr(key);
+    const toRemove = new Set(toArray2(values).map(toStr));
+    transaction.push(() => {
+      var _a, _b;
+      const existing = (_a = this.buckets.get(bucket)) == null ? void 0 : _a.get(keyStr);
+      if (existing) {
+        (_b = this.buckets.get(bucket)) == null ? void 0 : _b.set(
+          keyStr,
+          existing.filter((value) => !toRemove.has(value))
+        );
+      }
+    });
+  }
+};
+
+// src/backends/redis.ts
+var toArray3 = (value) => Array.isArray(value) ? value : [value];
+var toStr2 = (value) => `${value}`;
+var RedisBackend = class {
+  redis;
+  prefix;
+  constructor(redis, prefix = "acl") {
+    this.redis = redis;
+    this.prefix = prefix;
+  }
+  begin() {
+    return this.redis.multi();
+  }
+  async end(transaction) {
+    await transaction.exec();
+  }
+  async clean() {
+    const keys = await this.redis.keys(`${this.prefix}*`);
+    if (keys.length) {
+      await this.redis.del(keys);
+    }
+  }
+  get(bucket, key) {
+    return this.redis.sMembers(this.bucketKey(bucket, key));
+  }
+  async unions(buckets, keys) {
+    const result = {};
+    await Promise.all(
+      buckets.map(async (bucket) => {
+        result[bucket] = await this.redis.sUnion(this.bucketKeys(bucket, keys));
+      })
+    );
+    return result;
+  }
+  union(bucket, keys) {
+    return this.redis.sUnion(this.bucketKeys(bucket, keys));
+  }
+  add(transaction, bucket, key, values) {
+    transaction.sAdd(this.bucketKey(bucket, key), toArray3(values).map(toStr2));
+  }
+  del(transaction, bucket, keys) {
+    transaction.del(toArray3(keys).map((key) => this.bucketKey(bucket, key)));
+  }
+  remove(transaction, bucket, key, values) {
+    transaction.sRem(this.bucketKey(bucket, key), toArray3(values).map(toStr2));
+  }
+  bucketKey(bucket, key) {
+    return `${this.prefix}_${bucket}@${key}`;
+  }
+  bucketKeys(bucket, keys) {
+    return keys.map((key) => this.bucketKey(bucket, key));
+  }
+};
+
+// src/backends/mongodb.ts
+var SINGLE_COLLECTION = "resources";
+var toArray4 = (value) => Array.isArray(value) ? value : [value];
+function encode(text) {
+  if (typeof text === "string") {
+    return encodeURIComponent(text).replace(/\./g, "%2E");
+  }
+  return text;
+}
+var decode = (text) => decodeURIComponent(text);
+var MongoDBBackend = class {
+  db;
+  prefix;
+  useSingle;
+  useRawCollectionNames;
+  constructor(db, options = {}) {
+    this.db = db;
+    this.prefix = options.prefix ?? "";
+    this.useSingle = options.useSingle ?? false;
+    this.useRawCollectionNames = options.useRawCollectionNames ?? false;
+  }
+  begin() {
+    return [];
+  }
+  async end(transaction) {
+    for (const mutation of transaction) {
+      await mutation();
+    }
+  }
+  async clean() {
+    const collections = await this.db.collections();
+    await Promise.all(collections.map((collection) => collection.drop().catch(() => false)));
+  }
+  async get(bucket, key) {
+    const collection = this.collection(bucket);
+    const doc = await collection.findOne(this.filter(bucket, encode(key)), {
+      projection: { _bucketname: 0 }
+    });
+    if (!doc) {
+      return [];
+    }
+    return this.members(doc);
+  }
+  async union(bucket, keys) {
+    const collection = this.collection(bucket);
+    const filter = this.useSingle ? { _bucketname: bucket, key: { $in: keys.map(encode) } } : { key: { $in: keys.map(encode) } };
+    const docs = await collection.find(filter, { projection: { _bucketname: 0 } }).toArray();
+    const union2 = /* @__PURE__ */ new Set();
+    for (const doc of docs) {
+      for (const member of this.members(doc)) {
+        union2.add(member);
+      }
+    }
+    return [...union2];
+  }
+  add(transaction, bucket, key, values) {
+    if (key === "key") {
+      throw new Error("Key name 'key' is not allowed.");
+    }
+    const filter = this.filter(bucket, encode(key));
+    const doc = this.buildDoc(values);
+    transaction.push(async () => {
+      await this.collection(bucket).updateOne(filter, { $set: doc }, { upsert: true });
+    });
+    transaction.push(async () => {
+      await this.collection(bucket).createIndex({ _bucketname: 1, key: 1 });
+    });
+  }
+  del(transaction, bucket, keys) {
+    const encoded = toArray4(keys).map(encode);
+    const filter = this.useSingle ? { _bucketname: bucket, key: { $in: encoded } } : { key: { $in: encoded } };
+    transaction.push(async () => {
+      await this.collection(bucket).deleteMany(filter);
+    });
+  }
+  remove(transaction, bucket, key, values) {
+    const filter = this.filter(bucket, encode(key));
+    const doc = this.buildDoc(values);
+    transaction.push(async () => {
+      await this.collection(bucket).updateOne(filter, { $unset: doc }, { upsert: true });
+    });
+  }
+  // --- helpers ---------------------------------------------------------------
+  collection(bucket) {
+    const name = this.useSingle ? SINGLE_COLLECTION : bucket;
+    return this.db.collection(this.prefix + this.sanitizeCollectionName(name));
+  }
+  filter(bucket, key) {
+    return this.useSingle ? { _bucketname: bucket, key } : { key };
+  }
+  /** Build a `{ <encoded member>: true }` doc from one or many values. */
+  buildDoc(values) {
+    const doc = {};
+    for (const value of toArray4(values)) {
+      doc[`${encode(value)}`] = true;
+    }
+    return doc;
+  }
+  /** Decode a stored document's field names back into set members. */
+  members(doc) {
+    return Object.keys(doc).filter((field) => field !== "key" && field !== "_id").map(decode);
+  }
+  sanitizeCollectionName(name) {
+    if (this.useRawCollectionNames) {
+      return name;
+    }
+    return decodeURIComponent(name).replace(/[/\s]/g, "_");
+  }
+};
+
+// src/index.ts
+var VERSION = "1.0.0-alpha.0";
+
+export { Acl, HttpError, MemoryBackend, MongoDBBackend, RedisBackend, VERSION, aclErrorHandler, aclMiddleware, Acl as default };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map