@mahiframework/permissions 0.1.4

package/dist/permissions-config.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The optional `"permissions"` config namespace.
+ *
+ * Every field has a default, so an app that never writes
+ * `config/permissions.ts` gets a working package: roles scoped to the
+ * app's default auth guard, a day-long cache in the default store, and
+ * the gate hook registered.
+ *
+ * NOTHING HERE IMPORTS A MODEL. A `config/*.ts` is loaded before
+ * `app.bootstrap()`, so importing a model would pull the ORM into
+ * config-load time.
+ */
+export interface PermissionsConfig {
+    /**
+     * The guard name stamped on new roles and permissions, and used by any
+     * check that doesn't name one.
+     *
+     * Defaults to `auth.default`, which is what a single-guard app wants
+     * and never has to think about. A multi-guard app that wants `api`
+     * roles passes `{ guard: "api" }` per call; this is only the fallback.
+     *
+     * There is no wildcard guard. See the migration for why the column
+     * cannot be nullable.
+     */
+    guard?: string;
+    cache?: PermissionsCacheConfig;
+    /**
+     * Register the `Gate.before()` hook that makes `can("posts.edit")`
+     * consult permissions.
+     *
+     * On by default: it is the headline integration, and an app that
+     * installs this package and then finds `can()` ignores it has been
+     * surprised in the expensive direction. Set `false` to check only
+     * through this package's own API and middleware.
+     */
+    gate?: boolean;
+}
+export interface PermissionsCacheConfig {
+    /**
+     * The single key holding the whole role/permission map.
+     *
+     * One key, not one per entity, because `@mahiframework/cache` has no
+     * tags: there is no way to flush by pattern, so every key this package
+     * writes is a key it must be able to name later. One is nameable.
+     */
+    key?: string;
+    /** A named cache store, else the default one. */
+    store?: string;
+    /**
+     * How long the map survives, in seconds. Defaults to 24 hours.
+     *
+     * A TTL rather than no-expiry specifically BECAUSE there are no cache
+     * tags. Invalidation here is explicit `forget()` on write plus model-
+     * event listeners, and if some path ever escapes both, a `null` TTL
+     * would make the stale map permanent. A day is short enough that a
+     * missed invalidation is an incident with an end, and long enough that
+     * the map is effectively always warm.
+     */
+    ttlSeconds?: number;
+}
+/** The config with every default applied, built once at provider boot. */
+export interface ResolvedPermissionsConfig {
+    /** Null when neither config nor `auth.default` named one; resolved lazily so boot doesn't fail. */
+    guard: string | null;
+    cacheKey: string;
+    cacheStore: string | undefined;
+    cacheTtlSeconds: number;
+    gate: boolean;
+}
+/**
+ * Normalise a config block once, at provider boot.
+ *
+ * Every default is applied here with `??`, which is both the single place
+ * to read them and immune to merge-order surprises: contributing them via
+ * `ConfigRepository.merge()` would deep-merge the INCOMING values last
+ * and silently overwrite the app's own config rather than layering under
+ * it.
+ */
+export declare function resolveConfig(config?: PermissionsConfig): ResolvedPermissionsConfig;
+//# sourceMappingURL=permissions-config.d.ts.map

package/dist/permissions-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions-config.d.ts","sourceRoot":"","sources":["../src/permissions-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;;;OAUG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,KAAK,CAAC,EAAE,sBAAsB,CAAC;IAE/B;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,0EAA0E;AAC1E,MAAM,WAAW,yBAAyB;IACxC,mGAAmG;IACnG,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,eAAe,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,OAAO,CAAC;CACf;AAKD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,MAAM,GAAE,iBAAsB,GAAG,yBAAyB,CAUvF"}

package/dist/permissions-config.js

@@ -0,0 +1,22 @@
+const DEFAULT_CACHE_KEY = "mahi.permissions";
+const DEFAULT_TTL_SECONDS = 86_400;
+/**
+ * Normalise a config block once, at provider boot.
+ *
+ * Every default is applied here with `??`, which is both the single place
+ * to read them and immune to merge-order surprises: contributing them via
+ * `ConfigRepository.merge()` would deep-merge the INCOMING values last
+ * and silently overwrite the app's own config rather than layering under
+ * it.
+ */
+export function resolveConfig(config = {}) {
+    const cache = config.cache ?? {};
+    return {
+        guard: config.guard ?? null,
+        cacheKey: cache.key ?? DEFAULT_CACHE_KEY,
+        cacheStore: cache.store,
+        cacheTtlSeconds: cache.ttlSeconds ?? DEFAULT_TTL_SECONDS,
+        gate: config.gate ?? true,
+    };
+}
+//# sourceMappingURL=permissions-config.js.map

package/dist/permissions-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions-config.js","sourceRoot":"","sources":["../src/permissions-config.ts"],"names":[],"mappings":"AA4EA,MAAM,iBAAiB,GAAG,kBAAkB,CAAC;AAC7C,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAEnC;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,SAA4B,EAAE;IAC1D,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC;IAEjC,OAAO;QACL,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,IAAI;QAC3B,QAAQ,EAAE,KAAK,CAAC,GAAG,IAAI,iBAAiB;QACxC,UAAU,EAAE,KAAK,CAAC,KAAK;QACvB,eAAe,EAAE,KAAK,CAAC,UAAU,IAAI,mBAAmB;QACxD,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,IAAI;KAC1B,CAAC;AACJ,CAAC"}

package/dist/permissions-facade.d.ts

@@ -0,0 +1,74 @@
+import type { Assignee } from "./assignee.js";
+import type { Permission } from "./models/permission.model.js";
+import type { Role } from "./models/role.model.js";
+import type { GuardOption, PermissionRef, PermissionRegistrar, RoleRef } from "./permission-registrar.js";
+declare const Permissions_base: {
+    new (): {};
+    _swapped?: PermissionRegistrar | undefined;
+    instance(): PermissionRegistrar;
+    swap<S extends Partial<PermissionRegistrar>>(fake: S): S;
+    restore(): void;
+    isSwapped(): boolean;
+};
+/**
+ * Thin facade over the `PermissionRegistrar` singleton bound at
+ * `PERMISSIONS_TOKEN`.
+ *
+ *   await Permissions.assignRole(user, "admin");
+ *   if (await Permissions.hasPermissionTo(user, "posts.edit")) { ... }
+ *
+ * Every method takes the subject explicitly. Laravel's spatie package
+ * reads `$user->assignRole(...)` off a trait, and this framework has no
+ * traits and no package that touches the app's `User` model — behaviour
+ * is attached through a container singleton, never by extending a model
+ * the app owns. The explicit subject also works where a method could
+ * not: on any polymorphic entity uniformly, and in a queue job holding
+ * only a `{ type, id }` descriptor.
+ *
+ * Every call is `async`. There is no synchronous variant, and there
+ * cannot be: the first check of a process reads the database.
+ */
+export declare class Permissions extends Permissions_base {
+    static createRole(name: string, options?: GuardOption): Promise<Role>;
+    static createPermission(name: string, options?: GuardOption): Promise<Permission>;
+    static findOrCreateRole(name: string, options?: GuardOption): Promise<Role>;
+    static findOrCreatePermission(name: string, options?: GuardOption): Promise<Permission>;
+    static findRole(name: string, options?: GuardOption): Promise<Role>;
+    static findPermission(name: string, options?: GuardOption): Promise<Permission>;
+    static deleteRole(role: RoleRef, options?: GuardOption): Promise<void>;
+    static deletePermission(permission: PermissionRef, options?: GuardOption): Promise<void>;
+    static givePermissionToRole(role: RoleRef, permissions: PermissionRef | PermissionRef[], options?: GuardOption): Promise<void>;
+    static revokePermissionFromRole(role: RoleRef, permissions: PermissionRef | PermissionRef[], options?: GuardOption): Promise<void>;
+    static syncRolePermissions(role: RoleRef, permissions: PermissionRef | PermissionRef[], options?: GuardOption): Promise<void>;
+    static assignRole(assignee: Assignee, roles: RoleRef | RoleRef[], options?: GuardOption): Promise<void>;
+    static removeRole(assignee: Assignee, roles: RoleRef | RoleRef[], options?: GuardOption): Promise<void>;
+    /** Makes the subject's roles exactly `roles`. An empty array removes all of them. */
+    static syncRoles(assignee: Assignee, roles: RoleRef | RoleRef[], options?: GuardOption): Promise<void>;
+    static givePermissionTo(assignee: Assignee, permissions: PermissionRef | PermissionRef[], options?: GuardOption): Promise<void>;
+    static revokePermissionTo(assignee: Assignee, permissions: PermissionRef | PermissionRef[], options?: GuardOption): Promise<void>;
+    /** Makes the subject's DIRECT permissions exactly `permissions`. Roles are untouched. */
+    static syncPermissions(assignee: Assignee, permissions: PermissionRef | PermissionRef[], options?: GuardOption): Promise<void>;
+    static hasRole(assignee: Assignee, role: string | bigint, options?: GuardOption): Promise<boolean>;
+    static hasAnyRole(assignee: Assignee, roles: Array<string | bigint>, options?: GuardOption): Promise<boolean>;
+    static hasAllRoles(assignee: Assignee, roles: Array<string | bigint>, options?: GuardOption): Promise<boolean>;
+    /** True if the subject holds this permission by ANY route: a role, or directly. */
+    static hasPermissionTo(assignee: Assignee, permission: string | bigint, options?: GuardOption): Promise<boolean>;
+    static hasAnyPermission(assignee: Assignee, permissions: Array<string | bigint>, options?: GuardOption): Promise<boolean>;
+    static hasAllPermissions(assignee: Assignee, permissions: Array<string | bigint>, options?: GuardOption): Promise<boolean>;
+    /** True only if granted directly. A permission held via a role answers false here. */
+    static hasDirectPermission(assignee: Assignee, permission: string | bigint, options?: GuardOption): Promise<boolean>;
+    static getRoleNames(assignee: Assignee, options?: GuardOption): Promise<Set<string>>;
+    static getAllPermissions(assignee: Assignee, options?: GuardOption): Promise<Set<string>>;
+    static getDirectPermissions(assignee: Assignee, options?: GuardOption): Promise<Set<string>>;
+    static getPermissionsViaRoles(assignee: Assignee, options?: GuardOption): Promise<Set<string>>;
+    /** Drop the cached role/permission map and every memoised assignment. */
+    static forgetCache(): Promise<void>;
+    /**
+     * Run `callback` with a per-subject assignment memo, for a job or
+     * command that makes several checks. HTTP requests already have one,
+     * opened by the provider's middleware.
+     */
+    static withCache<T>(callback: () => T | Promise<T>): Promise<T>;
+}
+export {};
+//# sourceMappingURL=permissions-facade.d.ts.map

package/dist/permissions-facade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions-facade.d.ts","sourceRoot":"","sources":["../src/permissions-facade.ts"],"names":[],"mappings":"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"}

package/dist/permissions-facade.js

@@ -0,0 +1,131 @@
+import { Facade } from "@mahiframework/facades";
+import { withPermissionCache } from "./request-cache.js";
+import { PERMISSIONS_TOKEN } from "./tokens.js";
+/**
+ * Thin facade over the `PermissionRegistrar` singleton bound at
+ * `PERMISSIONS_TOKEN`.
+ *
+ *   await Permissions.assignRole(user, "admin");
+ *   if (await Permissions.hasPermissionTo(user, "posts.edit")) { ... }
+ *
+ * Every method takes the subject explicitly. Laravel's spatie package
+ * reads `$user->assignRole(...)` off a trait, and this framework has no
+ * traits and no package that touches the app's `User` model — behaviour
+ * is attached through a container singleton, never by extending a model
+ * the app owns. The explicit subject also works where a method could
+ * not: on any polymorphic entity uniformly, and in a queue job holding
+ * only a `{ type, id }` descriptor.
+ *
+ * Every call is `async`. There is no synchronous variant, and there
+ * cannot be: the first check of a process reads the database.
+ */
+export class Permissions extends Facade(() => PERMISSIONS_TOKEN) {
+    // --------------------------------------------------------- roles/permissions
+    static createRole(name, options) {
+        return this.instance().createRole(name, options);
+    }
+    static createPermission(name, options) {
+        return this.instance().createPermission(name, options);
+    }
+    static findOrCreateRole(name, options) {
+        return this.instance().findOrCreateRole(name, options);
+    }
+    static findOrCreatePermission(name, options) {
+        return this.instance().findOrCreatePermission(name, options);
+    }
+    static findRole(name, options) {
+        return this.instance().findRole(name, options);
+    }
+    static findPermission(name, options) {
+        return this.instance().findPermission(name, options);
+    }
+    static deleteRole(role, options) {
+        return this.instance().deleteRole(role, options);
+    }
+    static deletePermission(permission, options) {
+        return this.instance().deletePermission(permission, options);
+    }
+    // ------------------------------------------------------ role -> permissions
+    static givePermissionToRole(role, permissions, options) {
+        return this.instance().givePermissionToRole(role, permissions, options);
+    }
+    static revokePermissionFromRole(role, permissions, options) {
+        return this.instance().revokePermissionFromRole(role, permissions, options);
+    }
+    static syncRolePermissions(role, permissions, options) {
+        return this.instance().syncRolePermissions(role, permissions, options);
+    }
+    // ---------------------------------------------------------- subject -> roles
+    static assignRole(assignee, roles, options) {
+        return this.instance().assignRole(assignee, roles, options);
+    }
+    static removeRole(assignee, roles, options) {
+        return this.instance().removeRole(assignee, roles, options);
+    }
+    /** Makes the subject's roles exactly `roles`. An empty array removes all of them. */
+    static syncRoles(assignee, roles, options) {
+        return this.instance().syncRoles(assignee, roles, options);
+    }
+    // ---------------------------------------------------- subject -> permissions
+    static givePermissionTo(assignee, permissions, options) {
+        return this.instance().givePermissionTo(assignee, permissions, options);
+    }
+    static revokePermissionTo(assignee, permissions, options) {
+        return this.instance().revokePermissionTo(assignee, permissions, options);
+    }
+    /** Makes the subject's DIRECT permissions exactly `permissions`. Roles are untouched. */
+    static syncPermissions(assignee, permissions, options) {
+        return this.instance().syncPermissions(assignee, permissions, options);
+    }
+    // --------------------------------------------------------------- the checks
+    static hasRole(assignee, role, options) {
+        return this.instance().hasRole(assignee, role, options);
+    }
+    static hasAnyRole(assignee, roles, options) {
+        return this.instance().hasAnyRole(assignee, roles, options);
+    }
+    static hasAllRoles(assignee, roles, options) {
+        return this.instance().hasAllRoles(assignee, roles, options);
+    }
+    /** True if the subject holds this permission by ANY route: a role, or directly. */
+    static hasPermissionTo(assignee, permission, options) {
+        return this.instance().hasPermissionTo(assignee, permission, options);
+    }
+    static hasAnyPermission(assignee, permissions, options) {
+        return this.instance().hasAnyPermission(assignee, permissions, options);
+    }
+    static hasAllPermissions(assignee, permissions, options) {
+        return this.instance().hasAllPermissions(assignee, permissions, options);
+    }
+    /** True only if granted directly. A permission held via a role answers false here. */
+    static hasDirectPermission(assignee, permission, options) {
+        return this.instance().hasDirectPermission(assignee, permission, options);
+    }
+    // ------------------------------------------------------------ introspection
+    static getRoleNames(assignee, options) {
+        return this.instance().getRoleNames(assignee, options);
+    }
+    static getAllPermissions(assignee, options) {
+        return this.instance().getAllPermissions(assignee, options);
+    }
+    static getDirectPermissions(assignee, options) {
+        return this.instance().getDirectPermissions(assignee, options);
+    }
+    static getPermissionsViaRoles(assignee, options) {
+        return this.instance().getPermissionsViaRoles(assignee, options);
+    }
+    // -------------------------------------------------------------------- cache
+    /** Drop the cached role/permission map and every memoised assignment. */
+    static forgetCache() {
+        return this.instance().forgetCache();
+    }
+    /**
+     * Run `callback` with a per-subject assignment memo, for a job or
+     * command that makes several checks. HTTP requests already have one,
+     * opened by the provider's middleware.
+     */
+    static withCache(callback) {
+        return withPermissionCache(callback);
+    }
+}
+//# sourceMappingURL=permissions-facade.js.map

package/dist/permissions-facade.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions-facade.js","sourceRoot":"","sources":["../src/permissions-facade.ts"],"names":[],"mappings":"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"}

package/dist/permissions-service-provider.d.ts

@@ -0,0 +1,91 @@
+import { ServiceProvider } from "@mahiframework/core";
+import type { AnyModelClass, RegisteredMigration } from "@mahiframework/database";
+import type { GateRegistry } from "@mahiframework/authorization";
+import type { ListenerRegistration } from "@mahiframework/events";
+import type { HttpPipe } from "@mahiframework/http";
+import { PermissionsShowCommand } from "./commands/permissions-show.js";
+import { PERMISSIONS_TOKEN } from "./tokens.js";
+export { PERMISSIONS_TOKEN };
+/**
+ * Registers the `PermissionRegistrar` singleton, the gate hook that makes
+ * `can()` consult permissions, the per-request assignment memo, and the
+ * listeners that keep the cache honest.
+ *
+ * ORDERING: list this provider AFTER `DatabaseServiceProvider` (it owns
+ * five tables and two models), AFTER `CacheServiceProvider` (the map
+ * lives in a cache store), AFTER `AuthServiceProvider` (so its memo pipe
+ * runs inside the ambient auth scope and the subject is resolvable), and
+ * BEFORE `HttpServiceProvider` (so its pipe is collected before routes
+ * are). `AuthorizationServiceProvider` may come on either side:
+ * its own `boot()` walks every registered provider, so `gates()` is
+ * collected whichever order they appear in. You cannot enforce any of
+ * that; the app's `config/app.ts` decides, and this docstring is the
+ * whole mechanism.
+ */
+export declare class PermissionsServiceProvider extends ServiceProvider {
+    register(): void;
+    /**
+     * Teach the gate that a bare ability may be a permission name.
+     *
+     * This is what makes `can("posts.edit")`, `Gate.authorize("posts.edit")`
+     * and the `can()` route middleware consult permissions without any of
+     * them knowing this package exists. spatie registers the same hook.
+     *
+     * THREE THINGS HERE ARE LOAD-BEARING:
+     *
+     * 1. It returns `true` or `null`, NEVER `false`. A `false` from a
+     *    `before()` hook hard-denies and skips policy resolution entirely,
+     *    so denying on a permission miss would make every policy in the app
+     *    unreachable — the single worst bug this package could ship, and
+     *    the reason there is a test asserting a policy still grants after a
+     *    miss.
+     *
+     * 2. It abstains the moment the check carries an argument
+     *    (`args.length > 0`), which is a DELIBERATE DIVERGENCE FROM SPATIE.
+     *    There, `Gate::allows("update", $post)` also routes through the
+     *    permission check, so an app with both a permission named `update`
+     *    and a `PostPolicy.update` grants update on EVERY post to anyone
+     *    holding that permission. Abstaining splits the two cleanly: bare
+     *    abilities are permission names, model-scoped abilities are the
+     *    policy's business, and a policy that wants a permission check calls
+     *    `Permissions.hasPermissionTo()` explicitly — which is where that
+     *    decision belongs anyway, next to the row it concerns.
+     *
+     * 3. A non-model user abstains too. The pivots need a morph alias and a
+     *    `bigint` key; a token-guard adapter or a plain object has neither,
+     *    and `resolveAssignee()` would throw. A hook that throws turns every
+     *    authorization check in the app into a 500.
+     *
+     * `gates()` is synchronous, so nothing is loaded here. The closure is
+     * async and the first check of the process populates the cache.
+     *
+     * Hooks run in registration order and the first non-null wins, so a
+     * permission grant beats a later hook that would have denied. That
+     * ordering is the app's `config/app.ts` choice.
+     */
+    gates(gate: GateRegistry): void;
+    /**
+     * Open a per-request assignment memo.
+     *
+     * Not an optimisation so much as a correction: the gate hook above runs
+     * on EVERY authorization check, so a controller making five `can()`
+     * calls would be ten queries without this. See `request-cache.ts`.
+     */
+    middleware(): HttpPipe[];
+    /**
+     * Forget the cached map when a `Role` or `Permission` is written
+     * outside the registrar — a seeder, a migration, an admin screen.
+     * See the listener for why these three events and not a pattern.
+     */
+    listeners(): ReadonlyArray<ListenerRegistration>;
+    /**
+     * Static rather than a `migrations()` directory path, so it resolves
+     * inside a bundled binary. One migration for all five tables; see the
+     * file for why they are not five.
+     */
+    migrationSources(): RegisteredMigration[];
+    /** Registered so a queued job can carry a `Role` or a `Permission`. */
+    models(): AnyModelClass[];
+    commands(): (typeof PermissionsShowCommand)[];
+}
+//# sourceMappingURL=permissions-service-provider.d.ts.map

package/dist/permissions-service-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions-service-provider.d.ts","sourceRoot":"","sources":["../src/permissions-service-provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAElF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAClE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAQpD,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAGxE,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,EAAE,iBAAiB,EAAE,CAAC;AAE7B;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,0BAA2B,SAAQ,eAAe;IAC7D,QAAQ,IAAI,IAAI;IAiBhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;IACH,KAAK,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI;IAkB/B;;;;;;OAMG;IACH,UAAU,IAAI,QAAQ,EAAE;IAIxB;;;;OAIG;IACH,SAAS,IAAI,aAAa,CAAC,oBAAoB,CAAC;IAQhD;;;;OAIG;IACH,gBAAgB,IAAI,mBAAmB,EAAE;IAIzC,uEAAuE;IACvE,MAAM,IAAI,aAAa,EAAE;IAIzB,QAAQ;CAGT"}

package/dist/permissions-service-provider.js

@@ -0,0 +1,137 @@
+import { ServiceProvider } from "@mahiframework/core";
+import { BaseModel, ModelCreated, ModelDeleted, ModelUpdated } from "@mahiframework/database";
+import { PermissionRegistrar } from "./permission-registrar.js";
+import { resolveConfig } from "./permissions-config.js";
+import { Permission } from "./models/permission.model.js";
+import { Role } from "./models/role.model.js";
+import { InvalidatePermissionCacheListener } from "./listeners/invalidate-permission-cache.listener.js";
+import { PermissionsCacheResetCommand } from "./commands/permissions-cache-reset.js";
+import { PermissionsCheckCommand } from "./commands/permissions-check.js";
+import { PermissionsShowCommand } from "./commands/permissions-show.js";
+import createPermissionTables from "./migrations/0001_create_permission_tables.js";
+import { runWithPermissionCache } from "./request-cache.js";
+import { PERMISSIONS_TOKEN } from "./tokens.js";
+export { PERMISSIONS_TOKEN };
+/**
+ * Registers the `PermissionRegistrar` singleton, the gate hook that makes
+ * `can()` consult permissions, the per-request assignment memo, and the
+ * listeners that keep the cache honest.
+ *
+ * ORDERING: list this provider AFTER `DatabaseServiceProvider` (it owns
+ * five tables and two models), AFTER `CacheServiceProvider` (the map
+ * lives in a cache store), AFTER `AuthServiceProvider` (so its memo pipe
+ * runs inside the ambient auth scope and the subject is resolvable), and
+ * BEFORE `HttpServiceProvider` (so its pipe is collected before routes
+ * are). `AuthorizationServiceProvider` may come on either side:
+ * its own `boot()` walks every registered provider, so `gates()` is
+ * collected whichever order they appear in. You cannot enforce any of
+ * that; the app's `config/app.ts` decides, and this docstring is the
+ * whole mechanism.
+ */
+export class PermissionsServiceProvider extends ServiceProvider {
+    register() {
+        // No `config.merge()` of defaults. Every default is applied in
+        // `resolveConfig()` with `??`, which is both the single place to read
+        // them and immune to merge-order surprises: `ConfigRepository.merge()`
+        // deep-merges the INCOMING values last, so contributing defaults that
+        // way would silently overwrite the app's own config rather than
+        // layering under it.
+        this.app.singleton(PERMISSIONS_TOKEN, (app) => {
+            // `get`, not `require`: an app that installs the package and
+            // configures nothing gets working defaults (the auth default
+            // guard, a day-long cache) rather than a boot failure.
+            const config = app.config.get("permissions") ?? {};
+            return new PermissionRegistrar(app, resolveConfig(config));
+        });
+    }
+    /**
+     * Teach the gate that a bare ability may be a permission name.
+     *
+     * This is what makes `can("posts.edit")`, `Gate.authorize("posts.edit")`
+     * and the `can()` route middleware consult permissions without any of
+     * them knowing this package exists. spatie registers the same hook.
+     *
+     * THREE THINGS HERE ARE LOAD-BEARING:
+     *
+     * 1. It returns `true` or `null`, NEVER `false`. A `false` from a
+     *    `before()` hook hard-denies and skips policy resolution entirely,
+     *    so denying on a permission miss would make every policy in the app
+     *    unreachable — the single worst bug this package could ship, and
+     *    the reason there is a test asserting a policy still grants after a
+     *    miss.
+     *
+     * 2. It abstains the moment the check carries an argument
+     *    (`args.length > 0`), which is a DELIBERATE DIVERGENCE FROM SPATIE.
+     *    There, `Gate::allows("update", $post)` also routes through the
+     *    permission check, so an app with both a permission named `update`
+     *    and a `PostPolicy.update` grants update on EVERY post to anyone
+     *    holding that permission. Abstaining splits the two cleanly: bare
+     *    abilities are permission names, model-scoped abilities are the
+     *    policy's business, and a policy that wants a permission check calls
+     *    `Permissions.hasPermissionTo()` explicitly — which is where that
+     *    decision belongs anyway, next to the row it concerns.
+     *
+     * 3. A non-model user abstains too. The pivots need a morph alias and a
+     *    `bigint` key; a token-guard adapter or a plain object has neither,
+     *    and `resolveAssignee()` would throw. A hook that throws turns every
+     *    authorization check in the app into a 500.
+     *
+     * `gates()` is synchronous, so nothing is loaded here. The closure is
+     * async and the first check of the process populates the cache.
+     *
+     * Hooks run in registration order and the first non-null wins, so a
+     * permission grant beats a later hook that would have denied. That
+     * ordering is the app's `config/app.ts` choice.
+     */
+    gates(gate) {
+        const config = resolveConfig(this.app.config.get("permissions") ?? {});
+        if (!config.gate) {
+            return;
+        }
+        gate.before(async (user, ability, ...args) => {
+            if (args.length > 0 || !(user instanceof BaseModel)) {
+                return null;
+            }
+            const registrar = this.app.make(PERMISSIONS_TOKEN);
+            return (await registrar.hasPermissionTo(user, ability)) ? true : null;
+        });
+    }
+    /**
+     * Open a per-request assignment memo.
+     *
+     * Not an optimisation so much as a correction: the gate hook above runs
+     * on EVERY authorization check, so a controller making five `can()`
+     * calls would be ten queries without this. See `request-cache.ts`.
+     */
+    middleware() {
+        return [(request, next) => runWithPermissionCache(() => next(request))];
+    }
+    /**
+     * Forget the cached map when a `Role` or `Permission` is written
+     * outside the registrar — a seeder, a migration, an admin screen.
+     * See the listener for why these three events and not a pattern.
+     */
+    listeners() {
+        return [
+            [ModelCreated, InvalidatePermissionCacheListener],
+            [ModelUpdated, InvalidatePermissionCacheListener],
+            [ModelDeleted, InvalidatePermissionCacheListener],
+        ];
+    }
+    /**
+     * Static rather than a `migrations()` directory path, so it resolves
+     * inside a bundled binary. One migration for all five tables; see the
+     * file for why they are not five.
+     */
+    migrationSources() {
+        return [{ name: "0001_create_permission_tables", migration: createPermissionTables }];
+    }
+    /** Registered so a queued job can carry a `Role` or a `Permission`. */
+    models() {
+        return [Role, Permission];
+    }
+    commands() {
+        return [PermissionsCacheResetCommand, PermissionsCheckCommand, PermissionsShowCommand];
+    }
+}
+//# sourceMappingURL=permissions-service-provider.js.map

package/dist/permissions-service-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions-service-provider.js","sourceRoot":"","sources":["../src/permissions-service-provider.ts"],"names":[],"mappings":"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"}

package/dist/relations.d.ts

@@ -0,0 +1,63 @@
+import { Permission } from "./models/permission.model.js";
+import { Role } from "./models/role.model.js";
+/**
+ * The `roles` relation, for an app model that wants to eager-load them.
+ *
+ * Opt-in per model rather than shipped on anything, because the package
+ * owns neither the app's models nor its attribute interfaces:
+ *
+ *   export interface UserAttributes {
+ *     // ...
+ *     roles: MorphToMany<Role>;
+ *   }
+ *
+ *   export class User extends Model<UserAttributes>()({ ... }) {
+ *     static override relationships = {
+ *       roles: rolesRelation(),
+ *     };
+ *   }
+ *
+ * That buys `User.query().with("roles.permissions")` and
+ * `whereHas("roles", (q) => q.where("name", "admin"))`.
+ *
+ * READ-ONLY, in practice. `Permissions.assignRole()` writes the pivot
+ * directly (it takes a subject, not a relation handle, so it can also
+ * work from a `{ type, id }` descriptor in a job), so a collection
+ * loaded by `with("roles")` will not reflect an assignment made later in
+ * the same request. Re-`load()` it if that matters.
+ *
+ * `type` is deliberately omitted so it defaults to the DECLARING model's
+ * `morphAlias()` — which is what a `morphToMany` wants, and the opposite
+ * of what `morphedByMany` would. Note that `morphAlias()` falls back to
+ * the table name, so an app without a `Relation.morphMap()` entry has
+ * made its assignment rows depend on its table name.
+ */
+export declare function rolesRelation(): {
+    readonly type: "morphToMany";
+    readonly related: () => import("@mahiframework/database").ModelLike;
+    readonly options: import("@mahiframework/database").MorphToManyOptions<any, any>;
+    readonly __brand?: {
+        kind: "morphToMany";
+        related: Role;
+    } | undefined;
+};
+/**
+ * The `permissions` relation: permissions granted to this model
+ * DIRECTLY, never those inherited from its roles.
+ *
+ * The inherited ones have no relation to declare — they are two hops
+ * through `model_has_roles` and `role_has_permissions`, which is a
+ * `hasManyThrough` the ORM cannot express across a polymorphic pivot.
+ * `Permissions.getAllPermissions(user)` is the union, and it answers
+ * from the cached map rather than a join.
+ */
+export declare function permissionsRelation(): {
+    readonly type: "morphToMany";
+    readonly related: () => import("@mahiframework/database").ModelLike;
+    readonly options: import("@mahiframework/database").MorphToManyOptions<any, any>;
+    readonly __brand?: {
+        kind: "morphToMany";
+        related: Permission;
+    } | undefined;
+};
+//# sourceMappingURL=relations.d.ts.map

package/dist/relations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relations.d.ts","sourceRoot":"","sources":["../src/relations.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAC1D,OAAO,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,aAAa;;;;;;;;EAO5B;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB;;;;;;;;EAOlC"}