@mahiframework/permissions 0.1.4

package/dist/index.js

@@ -0,0 +1,18 @@
+export { PermissionsServiceProvider, PERMISSIONS_TOKEN } from "./permissions-service-provider.js";
+export { Permissions } from "./permissions-facade.js";
+export { PermissionRegistrar } from "./permission-registrar.js";
+export { Role } from "./models/role.model.js";
+export { Permission } from "./models/permission.model.js";
+export { rolesRelation, permissionsRelation } from "./relations.js";
+export { resolveAssignee, assigneeCacheKey } from "./assignee.js";
+export { resolveConfig } from "./permissions-config.js";
+export { role } from "./middleware/role.js";
+export { permission } from "./middleware/permission.js";
+export { roleOrPermission } from "./middleware/role-or-permission.js";
+export { withPermissionCache } from "./request-cache.js";
+export { InvalidatePermissionCacheListener } from "./listeners/invalidate-permission-cache.listener.js";
+export { PermissionsCacheResetCommand } from "./commands/permissions-cache-reset.js";
+export { PermissionsCheckCommand } from "./commands/permissions-check.js";
+export { PermissionsShowCommand } from "./commands/permissions-show.js";
+export { PermissionsError, RoleNotFoundError, PermissionNotFoundError, DuplicateNameError, UnsupportedAssigneeKeyError, UnresolvedGuardError, UnknownMorphAliasError, } from "./errors.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAClG,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAGhE,OAAO,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAE9C,OAAO,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAG1D,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAEpE,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAGlE,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAOxD,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAGtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAEzD,OAAO,EAAE,iCAAiC,EAAE,MAAM,qDAAqD,CAAC;AAExG,OAAO,EAAE,4BAA4B,EAAE,MAAM,uCAAuC,CAAC;AACrF,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAYxE,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,uBAAuB,EACvB,kBAAkB,EAClB,2BAA2B,EAC3B,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,aAAa,CAAC"}

package/dist/listeners/invalidate-permission-cache.listener.d.ts

@@ -0,0 +1,39 @@
+import type { Application } from "@mahiframework/core";
+import type { Listener } from "@mahiframework/events";
+import type { ModelLifecycleEvent } from "@mahiframework/database";
+/**
+ * Forgets the cached role/permission map when a `Role` or `Permission`
+ * row is written outside this package.
+ *
+ * `PermissionRegistrar` already forgets the cache on every write it
+ * performs, so this listener exists entirely for the writes it never
+ * sees: a seeder calling `Role.create(...)`, a migration backfilling
+ * `guard_name`, an admin screen saving a renamed role through the model.
+ * Without it, the map would keep answering from the old names until the
+ * TTL expired — which is precisely the class of bug a permission system
+ * cannot ship with.
+ *
+ * Subscribed to the three past-tense classes individually, not a
+ * `"model.*"` pattern. The pattern would also match `retrieved`, which
+ * fires on every row read in the application, so this would sit on the
+ * hottest path only to filter itself out. `ModelSaved` is skipped: it
+ * fires alongside both `ModelCreated` and `ModelUpdated` and would
+ * double the work. `ModelRestored` is skipped too — neither model uses
+ * soft deletes, so it cannot fire for them.
+ *
+ * ## Errors are not swallowed
+ *
+ * `EventDispatcher` awaits listeners with no isolation and
+ * `dispatchModelEvent` is awaited inside `save()`, so a throw here fails
+ * the caller's `Role.create()`. That is the right trade, and the opposite
+ * of the one `activity-logs` makes: a missing audit row is a lost record,
+ * but a cache that still grants a deleted role's permissions is a
+ * security failure. Better the write fails loudly and is retried than
+ * succeeds while leaving the cache lying.
+ */
+export declare class InvalidatePermissionCacheListener implements Listener<ModelLifecycleEvent> {
+    private readonly app;
+    constructor(app: Application);
+    handle(event: ModelLifecycleEvent): Promise<void>;
+}
+//# sourceMappingURL=invalidate-permission-cache.listener.d.ts.map

package/dist/listeners/invalidate-permission-cache.listener.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invalidate-permission-cache.listener.d.ts","sourceRoot":"","sources":["../../src/listeners/invalidate-permission-cache.listener.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAMnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,iCAAkC,YAAW,QAAQ,CAAC,mBAAmB,CAAC;IACzE,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,EAAE,WAAW;IAEvC,MAAM,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;CAWxD"}

package/dist/listeners/invalidate-permission-cache.listener.js

@@ -0,0 +1,50 @@
+import { PERMISSIONS_TOKEN } from "../tokens.js";
+import { Permission } from "../models/permission.model.js";
+import { Role } from "../models/role.model.js";
+/**
+ * Forgets the cached role/permission map when a `Role` or `Permission`
+ * row is written outside this package.
+ *
+ * `PermissionRegistrar` already forgets the cache on every write it
+ * performs, so this listener exists entirely for the writes it never
+ * sees: a seeder calling `Role.create(...)`, a migration backfilling
+ * `guard_name`, an admin screen saving a renamed role through the model.
+ * Without it, the map would keep answering from the old names until the
+ * TTL expired — which is precisely the class of bug a permission system
+ * cannot ship with.
+ *
+ * Subscribed to the three past-tense classes individually, not a
+ * `"model.*"` pattern. The pattern would also match `retrieved`, which
+ * fires on every row read in the application, so this would sit on the
+ * hottest path only to filter itself out. `ModelSaved` is skipped: it
+ * fires alongside both `ModelCreated` and `ModelUpdated` and would
+ * double the work. `ModelRestored` is skipped too — neither model uses
+ * soft deletes, so it cannot fire for them.
+ *
+ * ## Errors are not swallowed
+ *
+ * `EventDispatcher` awaits listeners with no isolation and
+ * `dispatchModelEvent` is awaited inside `save()`, so a throw here fails
+ * the caller's `Role.create()`. That is the right trade, and the opposite
+ * of the one `activity-logs` makes: a missing audit row is a lost record,
+ * but a cache that still grants a deleted role's permissions is a
+ * security failure. Better the write fails loudly and is retried than
+ * succeeds while leaving the cache lying.
+ */
+export class InvalidatePermissionCacheListener {
+    app;
+    constructor(app) {
+        this.app = app;
+    }
+    async handle(event) {
+        // Identity, not `morphAlias()`: an app may legitimately map `Role` to
+        // some other alias, and the question here is only whether the row
+        // that moved belongs to one of the two tables this cache is built
+        // from.
+        if (event.model !== Role && event.model !== Permission) {
+            return;
+        }
+        await this.app.make(PERMISSIONS_TOKEN).forgetCache();
+    }
+}
+//# sourceMappingURL=invalidate-permission-cache.listener.js.map

package/dist/listeners/invalidate-permission-cache.listener.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invalidate-permission-cache.listener.js","sourceRoot":"","sources":["../../src/listeners/invalidate-permission-cache.listener.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAC3D,OAAO,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,OAAO,iCAAiC;IACf;IAA7B,YAA6B,GAAgB;QAAhB,QAAG,GAAH,GAAG,CAAa;IAAG,CAAC;IAEjD,KAAK,CAAC,MAAM,CAAC,KAA0B;QACrC,sEAAsE;QACtE,kEAAkE;QAClE,kEAAkE;QAClE,QAAQ;QACR,IAAI,KAAK,CAAC,KAAK,KAAM,IAAc,IAAI,KAAK,CAAC,KAAK,KAAM,UAAoB,EAAE,CAAC;YAC7E,OAAO;QACT,CAAC;QAED,MAAM,IAAI,CAAC,GAAG,CAAC,IAAI,CAAsB,iBAAiB,CAAC,CAAC,WAAW,EAAE,CAAC;IAC5E,CAAC;CACF"}

package/dist/middleware/current-subject.d.ts

@@ -0,0 +1,23 @@
+import type { Assignee } from "../assignee.js";
+/**
+ * The authenticated subject, or null for a guest.
+ *
+ * Reads `AUTH_TOKEN` directly rather than `request.user()`, which wraps
+ * its lookup in a `try`/`catch` and returns `undefined` on any failure.
+ * That is the wrong shape here: it would turn "the route forgot
+ * `authenticate()`, so there is no auth scope at all" into "this is a
+ * guest", which is an authorization decision made by accident. The
+ * underlying `MissingAuthContextError` must propagate and 500, exactly
+ * as it does through `can()`.
+ *
+ * Returns null when auth isn't bound at all, so these pipes still behave
+ * (as deny) in an app with no authentication.
+ *
+ * Only a `BaseModel` is usable: the pivots need a morph alias and a
+ * `bigint` key, and a non-model user (a token-guard adapter, a stub)
+ * has neither. Treated as a guest rather than thrown, because a pipe's
+ * job is to answer allow/deny and a subject that cannot hold a role
+ * holds none.
+ */
+export declare function currentSubject(): Assignee | null;
+//# sourceMappingURL=current-subject.d.ts.map

package/dist/middleware/current-subject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"current-subject.d.ts","sourceRoot":"","sources":["../../src/middleware/current-subject.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAO/C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,IAAI,QAAQ,GAAG,IAAI,CAUhD"}

package/dist/middleware/current-subject.js

@@ -0,0 +1,31 @@
+import { app, AUTH_TOKEN } from "@mahiframework/core";
+import { BaseModel } from "@mahiframework/database";
+/**
+ * The authenticated subject, or null for a guest.
+ *
+ * Reads `AUTH_TOKEN` directly rather than `request.user()`, which wraps
+ * its lookup in a `try`/`catch` and returns `undefined` on any failure.
+ * That is the wrong shape here: it would turn "the route forgot
+ * `authenticate()`, so there is no auth scope at all" into "this is a
+ * guest", which is an authorization decision made by accident. The
+ * underlying `MissingAuthContextError` must propagate and 500, exactly
+ * as it does through `can()`.
+ *
+ * Returns null when auth isn't bound at all, so these pipes still behave
+ * (as deny) in an app with no authentication.
+ *
+ * Only a `BaseModel` is usable: the pivots need a morph alias and a
+ * `bigint` key, and a non-model user (a token-guard adapter, a stub)
+ * has neither. Treated as a guest rather than thrown, because a pipe's
+ * job is to answer allow/deny and a subject that cannot hold a role
+ * holds none.
+ */
+export function currentSubject() {
+    const container = app();
+    if (!container.has(AUTH_TOKEN)) {
+        return null;
+    }
+    const user = container.make(AUTH_TOKEN).userOrNull();
+    return user instanceof BaseModel ? user : null;
+}
+//# sourceMappingURL=current-subject.js.map

package/dist/middleware/current-subject.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"current-subject.js","sourceRoot":"","sources":["../../src/middleware/current-subject.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAQpD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,SAAS,GAAG,GAAG,EAAE,CAAC;IAExB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;QAC/B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAoB,UAAU,CAAC,CAAC,UAAU,EAAE,CAAC;IAExE,OAAO,IAAI,YAAY,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AACjD,CAAC"}

package/dist/middleware/permission.d.ts

@@ -0,0 +1,19 @@
+import { type HttpPipeFn } from "@mahiframework/http";
+import type { GuardOption } from "../permission-registrar.js";
+/**
+ * Require the authenticated subject to hold one of `permissions`, by
+ * either route (a role, or directly).
+ *
+ *   posts.patch("/{post}", update).middleware(authenticate(), permission("posts.edit"));
+ *
+ * ANY-of, as `role()` is. See that pipe for the guest/403 reasoning and
+ * the ordering constraint.
+ *
+ * `can("posts.edit")` from `@mahiframework/authorization` does the same
+ * thing, via the gate hook this package registers. Reach for this one
+ * when the gate hook is disabled (`permissions.gate: false`), when the
+ * check needs a non-default guard, or when the route should read as a
+ * permission check rather than an ability check.
+ */
+export declare function permission(permissions: string | string[], options?: GuardOption): HttpPipeFn;
+//# sourceMappingURL=permission.d.ts.map

package/dist/middleware/permission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission.d.ts","sourceRoot":"","sources":["../../src/middleware/permission.ts"],"names":[],"mappings":"AACA,OAAO,EAAa,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAuB,MAAM,4BAA4B,CAAC;AAInF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,OAAO,GAAE,WAAgB,GAAG,UAAU,CAkBhG"}

package/dist/middleware/permission.js

@@ -0,0 +1,34 @@
+import { app } from "@mahiframework/core";
+import { HttpError } from "@mahiframework/http";
+import { PERMISSIONS_TOKEN } from "../tokens.js";
+import { currentSubject } from "./current-subject.js";
+/**
+ * Require the authenticated subject to hold one of `permissions`, by
+ * either route (a role, or directly).
+ *
+ *   posts.patch("/{post}", update).middleware(authenticate(), permission("posts.edit"));
+ *
+ * ANY-of, as `role()` is. See that pipe for the guest/403 reasoning and
+ * the ordering constraint.
+ *
+ * `can("posts.edit")` from `@mahiframework/authorization` does the same
+ * thing, via the gate hook this package registers. Reach for this one
+ * when the gate hook is disabled (`permissions.gate: false`), when the
+ * check needs a non-default guard, or when the route should read as a
+ * permission check rather than an ability check.
+ */
+export function permission(permissions, options = {}) {
+    const names = Array.isArray(permissions) ? permissions : [permissions];
+    return async (request, next) => {
+        const subject = currentSubject();
+        if (subject === null) {
+            throw HttpError.forbidden();
+        }
+        const registrar = app().make(PERMISSIONS_TOKEN);
+        if (!(await registrar.hasAnyPermission(subject, names, options))) {
+            throw HttpError.forbidden();
+        }
+        return next(request);
+    };
+}
+//# sourceMappingURL=permission.js.map

package/dist/middleware/permission.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission.js","sourceRoot":"","sources":["../../src/middleware/permission.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,qBAAqB,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAmB,MAAM,qBAAqB,CAAC;AAEjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,UAAU,CAAC,WAA8B,EAAE,UAAuB,EAAE;IAClF,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;IAEvE,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE;QAC7B,MAAM,OAAO,GAAG,cAAc,EAAE,CAAC;QAEjC,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACrB,MAAM,SAAS,CAAC,SAAS,EAAE,CAAC;QAC9B,CAAC;QAED,MAAM,SAAS,GAAG,GAAG,EAAE,CAAC,IAAI,CAAsB,iBAAiB,CAAC,CAAC;QAErE,IAAI,CAAC,CAAC,MAAM,SAAS,CAAC,gBAAgB,CAAC,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;YACjE,MAAM,SAAS,CAAC,SAAS,EAAE,CAAC;QAC9B,CAAC;QAED,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC;IACvB,CAAC,CAAC;AACJ,CAAC"}

package/dist/middleware/role-or-permission.d.ts

@@ -0,0 +1,29 @@
+import { type HttpPipeFn } from "@mahiframework/http";
+import type { GuardOption } from "../permission-registrar.js";
+export interface RoleOrPermissionOptions extends GuardOption {
+    roles?: string[];
+    permissions?: string[];
+}
+/**
+ * Require the subject to hold one of `roles` OR one of `permissions`.
+ *
+ *   group.middleware(
+ *     authenticate(),
+ *     roleOrPermission({ roles: ["admin"], permissions: ["posts.edit"] }),
+ *   );
+ *
+ * A separate pipe rather than stacking `role()` and `permission()`,
+ * because stacking them is an AND: both would have to pass. This is the
+ * OR, and spatie's `role_or_permission:` middleware exists for the same
+ * reason.
+ *
+ * Takes a named object rather than two positional arrays: `roleOrPermission(
+ * ["admin"], ["posts.edit"])` is unreadable at the call site and silently
+ * wrong if the arguments are swapped, which is undetectable because both
+ * are `string[]`.
+ *
+ * Roles are checked first, so an admin costs no permission lookup. Both
+ * reads come from the same per-request memo regardless.
+ */
+export declare function roleOrPermission(options: RoleOrPermissionOptions): HttpPipeFn;
+//# sourceMappingURL=role-or-permission.d.ts.map

package/dist/middleware/role-or-permission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-or-permission.d.ts","sourceRoot":"","sources":["../../src/middleware/role-or-permission.ts"],"names":[],"mappings":"AACA,OAAO,EAAa,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAuB,MAAM,4BAA4B,CAAC;AAInF,MAAM,WAAW,uBAAwB,SAAQ,WAAW;IAC1D,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,UAAU,CA0B7E"}

package/dist/middleware/role-or-permission.js

@@ -0,0 +1,45 @@
+import { app } from "@mahiframework/core";
+import { HttpError } from "@mahiframework/http";
+import { PERMISSIONS_TOKEN } from "../tokens.js";
+import { currentSubject } from "./current-subject.js";
+/**
+ * Require the subject to hold one of `roles` OR one of `permissions`.
+ *
+ *   group.middleware(
+ *     authenticate(),
+ *     roleOrPermission({ roles: ["admin"], permissions: ["posts.edit"] }),
+ *   );
+ *
+ * A separate pipe rather than stacking `role()` and `permission()`,
+ * because stacking them is an AND: both would have to pass. This is the
+ * OR, and spatie's `role_or_permission:` middleware exists for the same
+ * reason.
+ *
+ * Takes a named object rather than two positional arrays: `roleOrPermission(
+ * ["admin"], ["posts.edit"])` is unreadable at the call site and silently
+ * wrong if the arguments are swapped, which is undetectable because both
+ * are `string[]`.
+ *
+ * Roles are checked first, so an admin costs no permission lookup. Both
+ * reads come from the same per-request memo regardless.
+ */
+export function roleOrPermission(options) {
+    const roles = options.roles ?? [];
+    const permissions = options.permissions ?? [];
+    return async (request, next) => {
+        const subject = currentSubject();
+        if (subject === null) {
+            throw HttpError.forbidden();
+        }
+        const registrar = app().make(PERMISSIONS_TOKEN);
+        if (roles.length > 0 && (await registrar.hasAnyRole(subject, roles, options))) {
+            return next(request);
+        }
+        if (permissions.length > 0 &&
+            (await registrar.hasAnyPermission(subject, permissions, options))) {
+            return next(request);
+        }
+        throw HttpError.forbidden();
+    };
+}
+//# sourceMappingURL=role-or-permission.js.map

package/dist/middleware/role-or-permission.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-or-permission.js","sourceRoot":"","sources":["../../src/middleware/role-or-permission.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,qBAAqB,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAmB,MAAM,qBAAqB,CAAC;AAEjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAOtD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAgC;IAC/D,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC;IAClC,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,EAAE,CAAC;IAE9C,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE;QAC7B,MAAM,OAAO,GAAG,cAAc,EAAE,CAAC;QAEjC,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACrB,MAAM,SAAS,CAAC,SAAS,EAAE,CAAC;QAC9B,CAAC;QAED,MAAM,SAAS,GAAG,GAAG,EAAE,CAAC,IAAI,CAAsB,iBAAiB,CAAC,CAAC;QAErE,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,MAAM,SAAS,CAAC,UAAU,CAAC,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;YAC9E,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC;QACvB,CAAC;QAED,IACE,WAAW,CAAC,MAAM,GAAG,CAAC;YACtB,CAAC,MAAM,SAAS,CAAC,gBAAgB,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC,EACjE,CAAC;YACD,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC;QACvB,CAAC;QAED,MAAM,SAAS,CAAC,SAAS,EAAE,CAAC;IAC9B,CAAC,CAAC;AACJ,CAAC"}

package/dist/middleware/role.d.ts

@@ -0,0 +1,21 @@
+import { type HttpPipeFn } from "@mahiframework/http";
+import type { GuardOption } from "../permission-registrar.js";
+/**
+ * Require the authenticated subject to hold one of `roles`.
+ *
+ *   admin.middleware(authenticate(), role("admin"));
+ *   admin.middleware(authenticate(), role(["admin", "editor"]));
+ *
+ * ANY-of, not all-of, matching spatie's `role:` middleware. For all-of,
+ * use `Permissions.hasAllRoles()` in the controller, where the intent is
+ * legible; a route string cannot express the difference and silently
+ * choosing one is how an app ends up with the wrong one.
+ *
+ * Place AFTER `authenticate()`. A guest is denied with 403, not 401,
+ * because 401 is not an authorization decision — the same stance the
+ * gate takes. `Router.middleware()` throws when called after a route is
+ * registered, so getting the order wrong inside a group is a boot
+ * failure rather than a hole.
+ */
+export declare function role(roles: string | string[], options?: GuardOption): HttpPipeFn;
+//# sourceMappingURL=role.d.ts.map

package/dist/middleware/role.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"role.d.ts","sourceRoot":"","sources":["../../src/middleware/role.ts"],"names":[],"mappings":"AACA,OAAO,EAAa,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAuB,MAAM,4BAA4B,CAAC;AAInF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,OAAO,GAAE,WAAgB,GAAG,UAAU,CAkBpF"}

package/dist/middleware/role.js

@@ -0,0 +1,36 @@
+import { app } from "@mahiframework/core";
+import { HttpError } from "@mahiframework/http";
+import { PERMISSIONS_TOKEN } from "../tokens.js";
+import { currentSubject } from "./current-subject.js";
+/**
+ * Require the authenticated subject to hold one of `roles`.
+ *
+ *   admin.middleware(authenticate(), role("admin"));
+ *   admin.middleware(authenticate(), role(["admin", "editor"]));
+ *
+ * ANY-of, not all-of, matching spatie's `role:` middleware. For all-of,
+ * use `Permissions.hasAllRoles()` in the controller, where the intent is
+ * legible; a route string cannot express the difference and silently
+ * choosing one is how an app ends up with the wrong one.
+ *
+ * Place AFTER `authenticate()`. A guest is denied with 403, not 401,
+ * because 401 is not an authorization decision — the same stance the
+ * gate takes. `Router.middleware()` throws when called after a route is
+ * registered, so getting the order wrong inside a group is a boot
+ * failure rather than a hole.
+ */
+export function role(roles, options = {}) {
+    const names = Array.isArray(roles) ? roles : [roles];
+    return async (request, next) => {
+        const subject = currentSubject();
+        if (subject === null) {
+            throw HttpError.forbidden();
+        }
+        const registrar = app().make(PERMISSIONS_TOKEN);
+        if (!(await registrar.hasAnyRole(subject, names, options))) {
+            throw HttpError.forbidden();
+        }
+        return next(request);
+    };
+}
+//# sourceMappingURL=role.js.map

package/dist/middleware/role.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"role.js","sourceRoot":"","sources":["../../src/middleware/role.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,qBAAqB,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAmB,MAAM,qBAAqB,CAAC;AAEjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,IAAI,CAAC,KAAwB,EAAE,UAAuB,EAAE;IACtE,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAErD,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE;QAC7B,MAAM,OAAO,GAAG,cAAc,EAAE,CAAC;QAEjC,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACrB,MAAM,SAAS,CAAC,SAAS,EAAE,CAAC;QAC9B,CAAC;QAED,MAAM,SAAS,GAAG,GAAG,EAAE,CAAC,IAAI,CAAsB,iBAAiB,CAAC,CAAC;QAErE,IAAI,CAAC,CAAC,MAAM,SAAS,CAAC,UAAU,CAAC,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;YAC3D,MAAM,SAAS,CAAC,SAAS,EAAE,CAAC;QAC9B,CAAC;QAED,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC;IACvB,CAAC,CAAC;AACJ,CAAC"}

package/dist/migrations/0001_create_permission_tables.d.ts

@@ -0,0 +1,63 @@
+import { type Migration } from "@mahiframework/database";
+/**
+ * All five permission tables in one migration, mirroring spatie's single
+ * `create_permission_tables`.
+ *
+ * One unit rather than five because the three pivots are meaningless
+ * without the two entity tables, and a partial rollback that left
+ * `model_has_roles` pointing at a dropped `roles` would be a worse state
+ * than either end of the migration.
+ *
+ * `roles` and `permissions` are identical in shape and deliberately kept
+ * as separate tables rather than one table with a `kind` column: the two
+ * are joined to each other (`role_has_permissions`), so a single table
+ * would need a self-referential pivot and every query would carry a
+ * `kind` predicate that the schema should have made impossible.
+ *
+ * `guard_name` is NOT NULL on both, and `(name, guard_name)` is unique.
+ * There is no "applies to every guard" value: a nullable `guard_name`
+ * cannot be made unique portably, because every engine treats NULLs as
+ * distinct in a unique index and the fix (`nullsNotDistinct`) is Postgres
+ * 15+ only and throws on SQLite/MySQL. Nullable would therefore have
+ * allowed unlimited duplicate `('admin', NULL)` rows, which is exactly
+ * the integrity this table exists to have.
+ *
+ * `id` on both is a `bigInteger` primary key, never auto-increment: the
+ * models assign a snowflake via `keyType: snowflake()`.
+ *
+ * COMPOSITE PRIMARY KEYS, not surrogate ids, on all three pivots. They
+ * ARE the dedupe mechanism: nothing in the framework deduplicates pivot
+ * inserts, so "assign the same role twice" has to be either a database
+ * error or a diffed write, and the constraint is what makes the first
+ * possible. `model_has_*` leads with the foreign id so the index also
+ * serves "who holds this role", with a second index on
+ * `(model_id, model_type)` for the far commoner "what does this subject
+ * hold".
+ *
+ * FOREIGN KEYS ON THE PACKAGE-OWNED SIDE ONLY. `role_id` and
+ * `permission_id` cascade on delete, because both tables are this
+ * package's and deleting a role must not leave assignments behind.
+ * `model_id` carries no foreign key at all: `users` is app-owned so the
+ * framework cannot assume its name, and the column holds the key of any
+ * assignable model. Same reasoning as `activity_logs.model_id` and
+ * `sessions.user_id`.
+ *
+ * `model_id` is a `bigInteger`, NOT text, which is the one place this
+ * schema diverges from `activity_logs`/`notifications`. Those tables are
+ * only ever read back by equality from code that already knows the type,
+ * so text (which holds every key type losslessly) costs them nothing.
+ * Here the column is the local side of a `morphToMany` pivot, and
+ * `buildPivotQuery()` binds the local key value RAW — a `bigint` against
+ * a `varchar` column makes Postgres raise `operator does not exist`. Text
+ * would therefore have broken the exported relation helpers, and with
+ * them `with("roles")` and `whereHas("roles", ...)`. The cost is that
+ * only snowflake-keyed models can hold roles, which
+ * `resolveAssignee()` enforces with a clear error rather than letting it
+ * reach SQL.
+ *
+ * No timestamps on the pivots. spatie has none either, and there is
+ * nothing to record: the composite key carries the entire fact.
+ */
+declare const migration: Migration;
+export default migration;
+//# sourceMappingURL=0001_create_permission_tables.d.ts.map

package/dist/migrations/0001_create_permission_tables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"0001_create_permission_tables.d.ts","sourceRoot":"","sources":["../../src/migrations/0001_create_permission_tables.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,KAAK,SAAS,EAAkB,MAAM,yBAAyB,CAAC;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,QAAA,MAAM,SAAS,EAAE,SAuDhB,CAAC;AAEF,eAAe,SAAS,CAAC"}

package/dist/migrations/0001_create_permission_tables.js

@@ -0,0 +1,113 @@
+import { Schema } from "@mahiframework/database";
+/**
+ * All five permission tables in one migration, mirroring spatie's single
+ * `create_permission_tables`.
+ *
+ * One unit rather than five because the three pivots are meaningless
+ * without the two entity tables, and a partial rollback that left
+ * `model_has_roles` pointing at a dropped `roles` would be a worse state
+ * than either end of the migration.
+ *
+ * `roles` and `permissions` are identical in shape and deliberately kept
+ * as separate tables rather than one table with a `kind` column: the two
+ * are joined to each other (`role_has_permissions`), so a single table
+ * would need a self-referential pivot and every query would carry a
+ * `kind` predicate that the schema should have made impossible.
+ *
+ * `guard_name` is NOT NULL on both, and `(name, guard_name)` is unique.
+ * There is no "applies to every guard" value: a nullable `guard_name`
+ * cannot be made unique portably, because every engine treats NULLs as
+ * distinct in a unique index and the fix (`nullsNotDistinct`) is Postgres
+ * 15+ only and throws on SQLite/MySQL. Nullable would therefore have
+ * allowed unlimited duplicate `('admin', NULL)` rows, which is exactly
+ * the integrity this table exists to have.
+ *
+ * `id` on both is a `bigInteger` primary key, never auto-increment: the
+ * models assign a snowflake via `keyType: snowflake()`.
+ *
+ * COMPOSITE PRIMARY KEYS, not surrogate ids, on all three pivots. They
+ * ARE the dedupe mechanism: nothing in the framework deduplicates pivot
+ * inserts, so "assign the same role twice" has to be either a database
+ * error or a diffed write, and the constraint is what makes the first
+ * possible. `model_has_*` leads with the foreign id so the index also
+ * serves "who holds this role", with a second index on
+ * `(model_id, model_type)` for the far commoner "what does this subject
+ * hold".
+ *
+ * FOREIGN KEYS ON THE PACKAGE-OWNED SIDE ONLY. `role_id` and
+ * `permission_id` cascade on delete, because both tables are this
+ * package's and deleting a role must not leave assignments behind.
+ * `model_id` carries no foreign key at all: `users` is app-owned so the
+ * framework cannot assume its name, and the column holds the key of any
+ * assignable model. Same reasoning as `activity_logs.model_id` and
+ * `sessions.user_id`.
+ *
+ * `model_id` is a `bigInteger`, NOT text, which is the one place this
+ * schema diverges from `activity_logs`/`notifications`. Those tables are
+ * only ever read back by equality from code that already knows the type,
+ * so text (which holds every key type losslessly) costs them nothing.
+ * Here the column is the local side of a `morphToMany` pivot, and
+ * `buildPivotQuery()` binds the local key value RAW — a `bigint` against
+ * a `varchar` column makes Postgres raise `operator does not exist`. Text
+ * would therefore have broken the exported relation helpers, and with
+ * them `with("roles")` and `whereHas("roles", ...)`. The cost is that
+ * only snowflake-keyed models can hold roles, which
+ * `resolveAssignee()` enforces with a clear error rather than letting it
+ * reach SQL.
+ *
+ * No timestamps on the pivots. spatie has none either, and there is
+ * nothing to record: the composite key carries the entire fact.
+ */
+const migration = {
+    async up() {
+        await Schema.create("roles", (table) => {
+            table.bigInteger("id").primary();
+            table.string("name");
+            table.string("guard_name");
+            table.timestamp("created_at");
+            table.timestamp("updated_at");
+            table.unique(["name", "guard_name"]);
+        });
+        await Schema.create("permissions", (table) => {
+            table.bigInteger("id").primary();
+            table.string("name");
+            table.string("guard_name");
+            table.timestamp("created_at");
+            table.timestamp("updated_at");
+            table.unique(["name", "guard_name"]);
+        });
+        await Schema.create("role_has_permissions", (table) => {
+            table.bigInteger("role_id");
+            table.bigInteger("permission_id");
+            table.primary(["role_id", "permission_id"]);
+            table.foreign("role_id").references("id").on("roles").cascadeOnDelete();
+            table.foreign("permission_id").references("id").on("permissions").cascadeOnDelete();
+        });
+        await Schema.create("model_has_roles", (table) => {
+            table.bigInteger("role_id");
+            table.string("model_type");
+            table.bigInteger("model_id");
+            table.primary(["role_id", "model_id", "model_type"]);
+            table.index(["model_id", "model_type"]);
+            table.foreign("role_id").references("id").on("roles").cascadeOnDelete();
+        });
+        await Schema.create("model_has_permissions", (table) => {
+            table.bigInteger("permission_id");
+            table.string("model_type");
+            table.bigInteger("model_id");
+            table.primary(["permission_id", "model_id", "model_type"]);
+            table.index(["model_id", "model_type"]);
+            table.foreign("permission_id").references("id").on("permissions").cascadeOnDelete();
+        });
+    },
+    /** Reverse creation order, so a pivot never outlives the table it references. */
+    async down() {
+        await Schema.drop("model_has_permissions");
+        await Schema.drop("model_has_roles");
+        await Schema.drop("role_has_permissions");
+        await Schema.drop("permissions");
+        await Schema.drop("roles");
+    },
+};
+export default migration;
+//# sourceMappingURL=0001_create_permission_tables.js.map

package/dist/migrations/0001_create_permission_tables.js.map

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