acl-next 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,346 @@
+/**
+ * Core domain types and the storage Backend interface.
+ *
+ * This is the typed, promise-native successor to the legacy lib/backend.js
+ * contract. Backends are namespaced (bucketed) key -> set-of-values stores
+ * with batched, committed writes.
+ */
+/** A user identifier. Users are created implicitly by assigning them roles. */
+type UserId = string | number;
+/** A role name. `"*"` is reserved to mean "all permissions". */
+type Role = string;
+/** A resource name (e.g. a URL or logical resource). */
+type Resource = string;
+/** A permission/action name (e.g. `"get"`, `"edit"`). */
+type Permission = string;
+/** A key within a bucket. */
+type Key = string | number;
+/** A value stored inside a bucket's set. */
+type StoredValue = string | number;
+/** One or many of `T` — mirrors the original "accepts string or array" API. */
+type OneOrMany<T> = T | T[];
+/** Optional logger; when provided, the Acl instance emits debug output. */
+interface Logger {
+    debug(...args: unknown[]): void;
+}
+/** Names of the internal storage buckets. Overridable via {@link AclOptions}. */
+interface Buckets {
+    meta: string;
+    parents: string;
+    permissions: string;
+    resources: string;
+    roles: string;
+    users: string;
+}
+/** Options accepted by the Acl constructor. */
+interface AclOptions {
+    buckets?: Partial<Buckets>;
+}
+/** A single entry of the array form of `allow(...)`. */
+interface AllowRule {
+    roles: OneOrMany<Role>;
+    allows: Array<{
+        resources: OneOrMany<Resource>;
+        permissions: OneOrMany<Permission>;
+    }>;
+}
+/**
+ * Storage backend interface.
+ *
+ * Writes are not applied immediately: callers obtain a transaction with
+ * {@link Backend.begin}, queue mutations with {@link Backend.add},
+ * {@link Backend.del} and {@link Backend.remove}, then commit them with
+ * {@link Backend.end}. Backends that support it commit atomically.
+ *
+ * @typeParam T - the backend-specific transaction type produced by `begin`.
+ */
+interface Backend<T = unknown> {
+    /** Start a transaction (a queue of pending mutations). */
+    begin(): T;
+    /** Commit a transaction. */
+    end(transaction: T): Promise<void>;
+    /** Remove all stored data. */
+    clean(): Promise<void>;
+    /** Get the set of values stored at `bucket`/`key` (empty array if none). */
+    get(bucket: string, key: Key): Promise<string[]>;
+    /** Union of the sets stored at the given `keys` within one `bucket`. */
+    union(bucket: string, keys: Key[]): Promise<string[]>;
+    /**
+     * Per-bucket union of `keys` across multiple `buckets`, keyed by bucket.
+     * Optional — Acl falls back to repeated {@link Backend.union} calls when a
+     * backend does not implement it.
+     */
+    unions?(buckets: string[], keys: Key[]): Promise<Record<string, string[]>>;
+    /** Queue: add `values` to the set at `bucket`/`key`. */
+    add(transaction: T, bucket: string, key: Key, values: OneOrMany<StoredValue>): void;
+    /** Queue: delete the given `keys` from `bucket`. */
+    del(transaction: T, bucket: string, keys: OneOrMany<Key>): void;
+    /** Queue: remove `values` from the set at `bucket`/`key`. */
+    remove(transaction: T, bucket: string, key: Key, values: OneOrMany<StoredValue>): void;
+}
+
+/**
+ * Minimal structural request shape the middleware needs. Compatible with
+ * Express (and most HTTP frameworks) without depending on their types.
+ */
+interface AclRequest {
+    originalUrl?: string;
+    url?: string;
+    method: string;
+    session?: {
+        userId?: UserId;
+    };
+    user?: {
+        id?: UserId;
+    };
+}
+interface AclResponse {
+    status(code: number): {
+        end(body?: string): unknown;
+        json(body: unknown): unknown;
+        send(body: unknown): unknown;
+    };
+}
+type AclNext = (err?: unknown) => void;
+type AclMiddleware = (req: AclRequest, res: AclResponse, next: AclNext) => void;
+/** Resolves the userId for a request when not supplied statically. */
+type UserIdResolver = (req: AclRequest, res: AclResponse) => UserId | undefined;
+/** Error thrown by the middleware; pair it with {@link aclErrorHandler}. */
+declare class HttpError extends Error {
+    readonly errorCode: number;
+    readonly name = "HttpError";
+    constructor(errorCode: number, message: string);
+}
+/**
+ * Build an Express-style middleware that authorizes the current request.
+ *
+ * @param acl                The Acl instance to check against.
+ * @param numPathComponents  How many leading URL path components form the
+ *                           resource name (default: the whole path).
+ * @param userId             A static user id, or a resolver `(req, res) => id`.
+ *                           Defaults to `req.session.userId` / `req.user.id`.
+ * @param actions            Permission(s) to check (default: the HTTP method).
+ */
+declare function aclMiddleware(acl: Acl, numPathComponents?: number, userId?: UserId | UserIdResolver, actions?: OneOrMany<Permission>): AclMiddleware;
+/**
+ * Express error handler that renders {@link HttpError}s. Pass `"json"` or
+ * `"html"` to choose the response format (defaults to plain text).
+ */
+declare function aclErrorHandler(contentType?: "json" | "html"): (err: unknown, req: AclRequest, res: AclResponse, next: AclNext) => void;
+
+/**
+ * Access Control List. Models authorization as users -> roles -> resources ->
+ * permissions, with role hierarchies (parents).
+ *
+ * Promise-native: every method returns a Promise (the legacy callback API is
+ * intentionally dropped). Storage is delegated to a {@link Backend}.
+ *
+ * @typeParam T - the backend transaction type.
+ */
+declare class Acl<T = unknown> {
+    readonly backend: Backend<T>;
+    readonly logger: Logger | undefined;
+    readonly buckets: Buckets;
+    constructor(backend: Backend<T>, logger?: Logger, options?: AclOptions);
+    /** Adds roles to a given user id. */
+    addUserRoles(userId: UserId, roles: OneOrMany<Role>): Promise<void>;
+    /** Removes roles from a given user id. */
+    removeUserRoles(userId: UserId, roles: OneOrMany<Role>): Promise<void>;
+    /** Returns all the roles assigned to a given user id. */
+    userRoles(userId: UserId): Promise<Role[]>;
+    /** Returns all users that have the given role. */
+    roleUsers(roleName: Role): Promise<UserId[]>;
+    /** Returns whether the user has the given role. */
+    hasRole(userId: UserId, role: Role): Promise<boolean>;
+    /** Adds one or more parent roles to a role. */
+    addRoleParents(role: Role, parents: OneOrMany<Role>): Promise<void>;
+    /** Removes parent role(s) from a role. Omit `parents` to remove all of them. */
+    removeRoleParents(role: Role, parents?: OneOrMany<Role>): Promise<void>;
+    /** Removes a role from the system, including all its permissions. */
+    removeRole(role: Role): Promise<void>;
+    /** Removes a resource from the system. */
+    removeResource(resource: Resource): Promise<void>;
+    /** Adds permissions to roles over resources (compact array form). */
+    allow(rules: AllowRule[]): Promise<void>;
+    /** Adds the given permissions to the given roles over the given resources. */
+    allow(roles: OneOrMany<Role>, resources: OneOrMany<Resource>, permissions: OneOrMany<Permission>): Promise<void>;
+    /** Removes permissions from a role over resources. Omit `permissions` to remove all. */
+    removeAllow(role: Role, resources: OneOrMany<Resource>, permissions?: OneOrMany<Permission>): Promise<void>;
+    /**
+     * 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.
+     */
+    removePermissions(role: Role, resources: Resource[], permissions: Permission[] | null): Promise<void>;
+    /**
+     * Returns, per resource, the permissions a user has. Uses the backend's
+     * `unions` optimization when available.
+     */
+    allowedPermissions(userId: UserId, resources: OneOrMany<Resource>): Promise<Record<Resource, Permission[]>>;
+    /** `allowedPermissions` variant using the backend `unions` bulk query. */
+    optimizedAllowedPermissions(userId: UserId, resources: OneOrMany<Resource>): Promise<Record<Resource, Permission[]>>;
+    /** Checks if a user is allowed all of the given permissions on a resource. */
+    isAllowed(userId: UserId, resource: Resource, permissions: OneOrMany<Permission>): Promise<boolean>;
+    /** Returns true if any of the roles has all of the given permissions. */
+    areAnyRolesAllowed(roles: OneOrMany<Role>, resource: Resource, permissions: OneOrMany<Permission>): Promise<boolean>;
+    /** Returns a map of resource -> permissions the roles have. */
+    whatResources(roles: OneOrMany<Role>): Promise<Record<Resource, Permission[]>>;
+    /** Returns the resources the roles have all of the given permissions over. */
+    whatResources(roles: OneOrMany<Role>, permissions: OneOrMany<Permission>): Promise<Resource[]>;
+    /** Backing implementation for {@link whatResources}. */
+    permittedResources(roles: OneOrMany<Role>, permissions?: Permission[]): Promise<Record<Resource, Permission[]> | Resource[]>;
+    /**
+     * 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?: number, userId?: UserId | UserIdResolver, actions?: OneOrMany<Permission>): AclMiddleware;
+    /** Compact array form of {@link allow}. */
+    private allowEx;
+    /** Direct parents of the given roles. */
+    private rolesParents;
+    /** All roles in the hierarchy, including the given roles. */
+    private allRoles;
+    /** All roles in the hierarchy of the given user. */
+    private allUserRoles;
+    /** All resources reachable by the given roles (through the hierarchy). */
+    private rolesResources;
+    /** Permissions the given roles (and their parents) have over a resource. */
+    private resourcePermissions;
+    /**
+     * Whether the roles (and their parents) satisfy all permissions on a resource.
+     *
+     * NOTE: does not handle circular role hierarchies.
+     */
+    private checkPermissions;
+}
+
+/** A queued mutation. The memory transaction is simply a list of these. */
+type Mutation = () => void;
+/** In-memory transaction: an ordered list of pending mutations. */
+type MemoryTransaction = Mutation[];
+/**
+ * In-memory storage backend. No external dependencies — ideal for tests and
+ * single-process apps. Data lives in a `Map<bucket, Map<key, values[]>>`.
+ */
+declare class MemoryBackend implements Backend<MemoryTransaction> {
+    private buckets;
+    begin(): MemoryTransaction;
+    end(transaction: MemoryTransaction): Promise<void>;
+    clean(): Promise<void>;
+    get(bucket: string, key: Key): Promise<string[]>;
+    unions(buckets: string[], keys: Key[]): Promise<Record<string, string[]>>;
+    union(bucket: string, keys: Key[]): Promise<string[]>;
+    add(transaction: MemoryTransaction, bucket: string, key: Key, values: OneOrMany<StoredValue>): void;
+    del(transaction: MemoryTransaction, bucket: string, keys: OneOrMany<Key>): void;
+    remove(transaction: MemoryTransaction, bucket: string, key: Key, values: OneOrMany<StoredValue>): void;
+}
+
+/**
+ * Minimal structural type for a node-redis v4+ client. Declared here (rather
+ * than importing from `redis`) so this module stays decoupled from the driver:
+ * any compatible client works, and consumers without `redis` installed can
+ * still type-check the rest of the package.
+ */
+interface RedisClientLike {
+    multi(): RedisMultiLike;
+    sMembers(key: string): Promise<string[]>;
+    sUnion(keys: string[]): Promise<string[]>;
+    keys(pattern: string): Promise<string[]>;
+    del(keys: string | string[]): Promise<number>;
+}
+interface RedisMultiLike {
+    sAdd(key: string, members: string | string[]): RedisMultiLike;
+    sRem(key: string, members: string | string[]): RedisMultiLike;
+    del(keys: string | string[]): RedisMultiLike;
+    exec(): Promise<unknown[]>;
+}
+/** Redis storage backend (node-redis v4+). Sets map directly to Redis sets. */
+declare class RedisBackend implements Backend<RedisMultiLike> {
+    private readonly redis;
+    private readonly prefix;
+    constructor(redis: RedisClientLike, prefix?: string);
+    begin(): RedisMultiLike;
+    end(transaction: RedisMultiLike): Promise<void>;
+    clean(): Promise<void>;
+    get(bucket: string, key: Key): Promise<string[]>;
+    unions(buckets: string[], keys: Key[]): Promise<Record<string, string[]>>;
+    union(bucket: string, keys: Key[]): Promise<string[]>;
+    add(transaction: RedisMultiLike, bucket: string, key: Key, values: OneOrMany<StoredValue>): void;
+    del(transaction: RedisMultiLike, bucket: string, keys: OneOrMany<Key>): void;
+    remove(transaction: RedisMultiLike, bucket: string, key: Key, values: OneOrMany<StoredValue>): void;
+    private bucketKey;
+    private bucketKeys;
+}
+
+/**
+ * Minimal structural types for the mongodb v4+ driver, declared here so this
+ * module stays decoupled from the driver (mongodb is an optional peer dep).
+ */
+interface MongoCollectionLike {
+    findOne(filter: object, options?: object): Promise<Record<string, unknown> | null>;
+    find(filter: object, options?: object): {
+        toArray(): Promise<Record<string, unknown>[]>;
+    };
+    updateOne(filter: object, update: object, options?: object): Promise<unknown>;
+    deleteMany(filter: object): Promise<unknown>;
+    createIndex(spec: object): Promise<string>;
+    drop(): Promise<boolean>;
+}
+interface MongoDbLike {
+    collection(name: string): MongoCollectionLike;
+    collections(): Promise<MongoCollectionLike[]>;
+}
+/** Each queued mutation is an async function; the transaction runs them in series. */
+type MongoTransaction = Array<() => Promise<void>>;
+interface MongoDBBackendOptions {
+    prefix?: string;
+    /** Store every bucket in one collection (distinguished by `_bucketname`). */
+    useSingle?: boolean;
+    /** Use bucket names verbatim as collection names (skip sanitization). */
+    useRawCollectionNames?: boolean;
+}
+/**
+ * MongoDB storage backend (mongodb v4+ driver).
+ *
+ * Each (bucket, key) pair is a document whose field names are the set members
+ * (stored as `{ <member>: true }`), since MongoDB has no native set type.
+ */
+declare class MongoDBBackend implements Backend<MongoTransaction> {
+    private readonly db;
+    private readonly prefix;
+    private readonly useSingle;
+    private readonly useRawCollectionNames;
+    constructor(db: MongoDbLike, options?: MongoDBBackendOptions);
+    begin(): MongoTransaction;
+    end(transaction: MongoTransaction): Promise<void>;
+    clean(): Promise<void>;
+    get(bucket: string, key: Key): Promise<string[]>;
+    union(bucket: string, keys: Key[]): Promise<string[]>;
+    add(transaction: MongoTransaction, bucket: string, key: Key, values: OneOrMany<StoredValue>): void;
+    del(transaction: MongoTransaction, bucket: string, keys: OneOrMany<Key>): void;
+    remove(transaction: MongoTransaction, bucket: string, key: Key, values: OneOrMany<StoredValue>): void;
+    private collection;
+    private filter;
+    /** Build a `{ <encoded member>: true }` doc from one or many values. */
+    private buildDoc;
+    /** Decode a stored document's field names back into set members. */
+    private members;
+    private sanitizeCollectionName;
+}
+
+/**
+ * acl-next — modern TypeScript ACL / RBAC.
+ *
+ * Fork of optimalbits/node_acl (MIT, (c) 2011-2013 Manuel Astudillo).
+ *
+ * Public surface is filled in across the modernization phases:
+ *   - Phase 2: types & Backend interface
+ *   - Phase 3: backends (memory, redis, mongodb)
+ *   - Phase 4: the Acl class
+ *   - Phase 5: express middleware
+ */
+declare const VERSION = "1.0.0-alpha.0";
+
+export { Acl, type AclMiddleware, type AclNext, type AclOptions, type AclRequest, type AclResponse, type AllowRule, type Backend, type Buckets, HttpError, type Key, type Logger, MemoryBackend, type MemoryTransaction, type MongoCollectionLike, MongoDBBackend, type MongoDBBackendOptions, type MongoDbLike, type MongoTransaction, type OneOrMany, type Permission, RedisBackend, type RedisClientLike, type RedisMultiLike, type Resource, type Role, type StoredValue, type UserId, type UserIdResolver, VERSION, aclErrorHandler, aclMiddleware, Acl as default };