@mahiframework/permissions 0.1.4

package/dist/models/permission.model.d.ts

@@ -0,0 +1,58 @@
+import { type BelongsToMany } from "@mahiframework/database";
+import type { DateTime } from "@mahiframework/datetime";
+import { Role } from "./role.model.js";
+/**
+ * A single named thing a subject may do: `"posts.edit"`, `"billing.view"`.
+ *
+ * A permission is a *name*, not a rule. It carries no model class, no
+ * row, no callback — holding `"posts.edit"` says nothing about *which*
+ * post. That is the Gate's job, and the deliberate reason this package's
+ * gate hook abstains the moment a check carries a model argument (see
+ * `PermissionsServiceProvider.gates()`).
+ *
+ * `guard_name` scopes the permission to one of the app's auth guards, so
+ * an `api`-guard permission cannot satisfy a `web`-guard check. It is NOT
+ * NULL and has no wildcard value: `(name, guard_name)` is unique, and a
+ * nullable column cannot be made unique portably (`nullsNotDistinct` is
+ * Postgres 15+ only and throws on SQLite/MySQL), so "applies to every
+ * guard" would have meant unlimited duplicate rows in dev.
+ */
+export interface PermissionAttributes {
+    /** A snowflake, hence `bigint`: a 64-bit id does not fit a `number`. */
+    id: bigint;
+    name: string;
+    /** The auth guard this permission belongs to, e.g. `"web"`. Never null. */
+    guard_name: string;
+    created_at: DateTime;
+    updated_at: DateTime;
+    /** Roles granting this permission, across `role_has_permissions`. */
+    roles: BelongsToMany<Role>;
+}
+declare const Permission_base: import("@mahiframework/database").ModelStatics<PermissionAttributes, {
+    readonly table: "permissions";
+    readonly primaryKey: "id";
+    readonly keyType: import("@mahiframework/database").KeyStrategy<bigint>;
+    readonly morphName: "Permission";
+}> & (new (attributes?: Partial<import("@mahiframework/database").WritableAttributes<PermissionAttributes, {
+    readonly table: "permissions";
+    readonly primaryKey: "id";
+    readonly keyType: import("@mahiframework/database").KeyStrategy<bigint>;
+    readonly morphName: "Permission";
+}>> | undefined) => import("@mahiframework/database").BaseModel & import("@mahiframework/database").ResolvedAttributes<PermissionAttributes> & {
+    relations: import("@mahiframework/database").RelationBuildersFor<PermissionAttributes>;
+} & import("@mahiframework/database").HasAttributes<PermissionAttributes>);
+export declare class Permission extends Permission_base {
+    static relationships: {
+        roles: {
+            readonly type: "belongsToMany";
+            readonly related: () => import("@mahiframework/database").ModelLike;
+            readonly options: import("@mahiframework/database").BelongsToManyOptions<any, any>;
+            readonly __brand?: {
+                kind: "belongsToMany";
+                related: Role;
+            } | undefined;
+        };
+    };
+}
+export {};
+//# sourceMappingURL=permission.model.d.ts.map

package/dist/models/permission.model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission.model.d.ts","sourceRoot":"","sources":["../../src/models/permission.model.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAEnF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAEvC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,oBAAoB;IACnC,wEAAwE;IACxE,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,QAAQ,CAAC;IACrB,UAAU,EAAE,QAAQ,CAAC;IACrB,qEAAqE;IACrE,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,CAAC;CAC5B;;;;;;;;;;;;;;AAED,qBAAa,UAAW,SAAQ,eAK9B;IACA,OAAgB,aAAa;;;;;;;;;;MAM3B;CACH"}

package/dist/models/permission.model.js

@@ -0,0 +1,18 @@
+import { Model, belongsToMany } from "@mahiframework/database";
+import { snowflake } from "@mahiframework/snowflake";
+import { Role } from "./role.model.js";
+export class Permission extends Model()({
+    table: "permissions",
+    primaryKey: "id",
+    keyType: snowflake(),
+    morphName: "Permission",
+}) {
+    static relationships = {
+        roles: belongsToMany(() => Role, {
+            pivotTable: "role_has_permissions",
+            foreignPivotKey: "permission_id",
+            relatedPivotKey: "role_id",
+        }),
+    };
+}
+//# sourceMappingURL=permission.model.js.map

package/dist/models/permission.model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission.model.js","sourceRoot":"","sources":["../../src/models/permission.model.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,aAAa,EAAsB,MAAM,yBAAyB,CAAC;AACnF,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAErD,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AA8BvC,MAAM,OAAO,UAAW,SAAQ,KAAK,EAAwB,CAAC;IAC5D,KAAK,EAAE,aAAa;IACpB,UAAU,EAAE,IAAI;IAChB,OAAO,EAAE,SAAS,EAAE;IACpB,SAAS,EAAE,YAAY;CACxB,CAAC;IACA,MAAM,CAAU,aAAa,GAAG;QAC9B,KAAK,EAAE,aAAa,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE;YAC/B,UAAU,EAAE,sBAAsB;YAClC,eAAe,EAAE,eAAe;YAChC,eAAe,EAAE,SAAS;SAC3B,CAAC;KACH,CAAC"}

package/dist/models/role.model.d.ts

@@ -0,0 +1,60 @@
+import { type BelongsToMany } from "@mahiframework/database";
+import type { DateTime } from "@mahiframework/datetime";
+import { Permission } from "./permission.model.js";
+/**
+ * A named bundle of permissions a subject can hold.
+ *
+ * The indirection is the whole point: a subject holding `"editor"`
+ * inherits every permission attached to it, so changing what an editor
+ * may do is one write instead of one per user. A permission can also be
+ * granted to a subject directly (`model_has_permissions`), which
+ * supplements roles rather than replacing them.
+ *
+ * `guard_name` is NOT NULL and scoped exactly as `Permission`'s is; see
+ * that model for why there is no wildcard guard.
+ *
+ * There is intentionally no `users` relation here. The inverse of the
+ * polymorphic assignment is a `morphedByMany`, which needs the *app's*
+ * model class, and this package does not know it. The docs show the three
+ * lines an app writes to declare it, and flag the `type`-defaulting
+ * asymmetry between `morphToMany` and `morphedByMany`.
+ */
+export interface RoleAttributes {
+    /** A snowflake, hence `bigint`: a 64-bit id does not fit a `number`. */
+    id: bigint;
+    name: string;
+    /** The auth guard this role belongs to, e.g. `"web"`. Never null. */
+    guard_name: string;
+    created_at: DateTime;
+    updated_at: DateTime;
+    /** Permissions this role grants, across `role_has_permissions`. */
+    permissions: BelongsToMany<Permission>;
+}
+declare const Role_base: import("@mahiframework/database").ModelStatics<RoleAttributes, {
+    readonly table: "roles";
+    readonly primaryKey: "id";
+    readonly keyType: import("@mahiframework/database").KeyStrategy<bigint>;
+    readonly morphName: "Role";
+}> & (new (attributes?: Partial<import("@mahiframework/database").WritableAttributes<RoleAttributes, {
+    readonly table: "roles";
+    readonly primaryKey: "id";
+    readonly keyType: import("@mahiframework/database").KeyStrategy<bigint>;
+    readonly morphName: "Role";
+}>> | undefined) => import("@mahiframework/database").BaseModel & import("@mahiframework/database").ResolvedAttributes<RoleAttributes> & {
+    relations: import("@mahiframework/database").RelationBuildersFor<RoleAttributes>;
+} & import("@mahiframework/database").HasAttributes<RoleAttributes>);
+export declare class Role extends Role_base {
+    static relationships: {
+        permissions: {
+            readonly type: "belongsToMany";
+            readonly related: () => import("@mahiframework/database").ModelLike;
+            readonly options: import("@mahiframework/database").BelongsToManyOptions<any, any>;
+            readonly __brand?: {
+                kind: "belongsToMany";
+                related: Permission;
+            } | undefined;
+        };
+    };
+}
+export {};
+//# sourceMappingURL=role.model.d.ts.map

package/dist/models/role.model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"role.model.d.ts","sourceRoot":"","sources":["../../src/models/role.model.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAEnF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAEnD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,QAAQ,CAAC;IACrB,UAAU,EAAE,QAAQ,CAAC;IACrB,mEAAmE;IACnE,WAAW,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;CACxC;;;;;;;;;;;;;;AAED,qBAAa,IAAK,SAAQ,SAKxB;IACA,OAAgB,aAAa;;;;;;;;;;MAM3B;CACH"}

package/dist/models/role.model.js

@@ -0,0 +1,18 @@
+import { Model, belongsToMany } from "@mahiframework/database";
+import { snowflake } from "@mahiframework/snowflake";
+import { Permission } from "./permission.model.js";
+export class Role extends Model()({
+    table: "roles",
+    primaryKey: "id",
+    keyType: snowflake(),
+    morphName: "Role",
+}) {
+    static relationships = {
+        permissions: belongsToMany(() => Permission, {
+            pivotTable: "role_has_permissions",
+            foreignPivotKey: "role_id",
+            relatedPivotKey: "permission_id",
+        }),
+    };
+}
+//# sourceMappingURL=role.model.js.map

package/dist/models/role.model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"role.model.js","sourceRoot":"","sources":["../../src/models/role.model.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,aAAa,EAAsB,MAAM,yBAAyB,CAAC;AACnF,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAErD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAgCnD,MAAM,OAAO,IAAK,SAAQ,KAAK,EAAkB,CAAC;IAChD,KAAK,EAAE,OAAO;IACd,UAAU,EAAE,IAAI;IAChB,OAAO,EAAE,SAAS,EAAE;IACpB,SAAS,EAAE,MAAM;CAClB,CAAC;IACA,MAAM,CAAU,aAAa,GAAG;QAC9B,WAAW,EAAE,aAAa,CAAC,GAAG,EAAE,CAAC,UAAU,EAAE;YAC3C,UAAU,EAAE,sBAAsB;YAClC,eAAe,EAAE,SAAS;YAC1B,eAAe,EAAE,eAAe;SACjC,CAAC;KACH,CAAC"}

package/dist/permission-map.d.ts

@@ -0,0 +1,97 @@
+/**
+ * The cached snapshot of every role, every permission, and which
+ * permissions each role grants.
+ *
+ * ONE cache entry for the whole table set, which is spatie's model and
+ * the only one `@mahiframework/cache` can support: it has no tags, so
+ * there is no flush-by-pattern, and every key written must be a key
+ * nameable later. One key is nameable. It is also bounded by the number
+ * of roles and permissions an app defines (tens, not millions), unlike a
+ * per-subject cache which grows with the user table.
+ *
+ * What is NOT in here: who holds what. `model_has_roles` scales with
+ * users, so caching it under one key would mean one entry growing without
+ * bound and invalidated by every assignment anywhere. Assignments are a
+ * query, memoised per request (see `request-cache.ts`).
+ *
+ * ## The serialisation boundary
+ *
+ * `RedisCacheStore` and `FileCacheStore` persist with `JSON.stringify`,
+ * and `JSON.stringify` THROWS on a `bigint` — deliberately, per
+ * `@mahiframework/snowflake`: an id cannot be serialised without a
+ * decision being made about it. The decision here is a decimal string,
+ * matching `Resource` and `Model.toJSON()`.
+ *
+ * So the cached form (`SerializedPermissionMap`) carries strings and the
+ * in-memory form (`PermissionMap`) carries `bigint`, with
+ * `serializeMap`/`deserializeMap` the only crossing. Getting this wrong
+ * is a bug that cannot be reproduced on `ArrayCacheStore`, which passes a
+ * `bigint` through happily — it would appear only once an app switched to
+ * redis or file, i.e. in production. Hence one module, two functions, and
+ * a test that round-trips through `JSON.parse(JSON.stringify(...))`.
+ */
+/** A role as cached: its identity plus the permissions it grants. */
+export interface MappedRole {
+    id: bigint;
+    name: string;
+    guardName: string;
+    /** Permission ids from `role_has_permissions`. */
+    permissionIds: bigint[];
+}
+/** A permission as cached. */
+export interface MappedPermission {
+    id: bigint;
+    name: string;
+    guardName: string;
+}
+/**
+ * The in-memory map, with lookup indexes derived once at
+ * deserialisation rather than scanned per check.
+ *
+ * Keyed by `name` + `guardName` together, because the same name can exist
+ * once per guard and a `web` role must not answer an `api` lookup.
+ */
+export interface PermissionMap {
+    roles: MappedRole[];
+    permissions: MappedPermission[];
+    /** `"{guard}\u0000{name}"` -> role. */
+    roleByName: Map<string, MappedRole>;
+    /** `"{guard}\u0000{name}"` -> permission. */
+    permissionByName: Map<string, MappedPermission>;
+    /** Role id -> role, for turning an assignment row into permissions. */
+    roleById: Map<bigint, MappedRole>;
+    /** Permission id -> permission, for naming a directly-assigned permission. */
+    permissionById: Map<bigint, MappedPermission>;
+}
+/** The JSON-safe form actually written to the cache store. */
+export interface SerializedPermissionMap {
+    roles: Array<{
+        id: string;
+        name: string;
+        guardName: string;
+        permissionIds: string[];
+    }>;
+    permissions: Array<{
+        id: string;
+        name: string;
+        guardName: string;
+    }>;
+}
+/**
+ * `"{guard}\0{name}"`.
+ *
+ * A NUL separator rather than `:` because a permission name is
+ * app-chosen and may contain anything printable (`"billing:view"` is a
+ * perfectly ordinary name), whereas a guard name comes from
+ * `config/auth.ts`. Without a separator that cannot appear in either
+ * half, `("web", "a:b")` and `("web:a", "b")` would collide — and the
+ * collision would grant a permission nobody assigned.
+ */
+export declare function mapKey(guardName: string, name: string): string;
+/** Strip the `bigint`s out, for the cache store. */
+export declare function serializeMap(map: PermissionMap): SerializedPermissionMap;
+/** Put the `bigint`s back, and build the lookup indexes. */
+export declare function deserializeMap(serialized: SerializedPermissionMap): PermissionMap;
+/** Assemble a map and its indexes from freshly-read rows. */
+export declare function buildMap(roles: MappedRole[], permissions: MappedPermission[]): PermissionMap;
+//# sourceMappingURL=permission-map.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"permission-map.d.ts","sourceRoot":"","sources":["../src/permission-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,qEAAqE;AACrE,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,8BAA8B;AAC9B,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,WAAW,EAAE,gBAAgB,EAAE,CAAC;IAChC,uCAAuC;IACvC,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACpC,6CAA6C;IAC7C,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAChD,uEAAuE;IACvE,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAClC,8EAA8E;IAC9E,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CAC/C;AAED,8DAA8D;AAC9D,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IACvF,WAAW,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrE;AAED;;;;;;;;;GASG;AACH,wBAAgB,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,oDAAoD;AACpD,wBAAgB,YAAY,CAAC,GAAG,EAAE,aAAa,GAAG,uBAAuB,CAcxE;AAED,4DAA4D;AAC5D,wBAAgB,cAAc,CAAC,UAAU,EAAE,uBAAuB,GAAG,aAAa,CAejF;AAED,6DAA6D;AAC7D,wBAAgB,QAAQ,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,WAAW,EAAE,gBAAgB,EAAE,GAAG,aAAa,CAiB5F"}

package/dist/permission-map.js

@@ -0,0 +1,93 @@
+/**
+ * The cached snapshot of every role, every permission, and which
+ * permissions each role grants.
+ *
+ * ONE cache entry for the whole table set, which is spatie's model and
+ * the only one `@mahiframework/cache` can support: it has no tags, so
+ * there is no flush-by-pattern, and every key written must be a key
+ * nameable later. One key is nameable. It is also bounded by the number
+ * of roles and permissions an app defines (tens, not millions), unlike a
+ * per-subject cache which grows with the user table.
+ *
+ * What is NOT in here: who holds what. `model_has_roles` scales with
+ * users, so caching it under one key would mean one entry growing without
+ * bound and invalidated by every assignment anywhere. Assignments are a
+ * query, memoised per request (see `request-cache.ts`).
+ *
+ * ## The serialisation boundary
+ *
+ * `RedisCacheStore` and `FileCacheStore` persist with `JSON.stringify`,
+ * and `JSON.stringify` THROWS on a `bigint` — deliberately, per
+ * `@mahiframework/snowflake`: an id cannot be serialised without a
+ * decision being made about it. The decision here is a decimal string,
+ * matching `Resource` and `Model.toJSON()`.
+ *
+ * So the cached form (`SerializedPermissionMap`) carries strings and the
+ * in-memory form (`PermissionMap`) carries `bigint`, with
+ * `serializeMap`/`deserializeMap` the only crossing. Getting this wrong
+ * is a bug that cannot be reproduced on `ArrayCacheStore`, which passes a
+ * `bigint` through happily — it would appear only once an app switched to
+ * redis or file, i.e. in production. Hence one module, two functions, and
+ * a test that round-trips through `JSON.parse(JSON.stringify(...))`.
+ */
+/**
+ * `"{guard}\0{name}"`.
+ *
+ * A NUL separator rather than `:` because a permission name is
+ * app-chosen and may contain anything printable (`"billing:view"` is a
+ * perfectly ordinary name), whereas a guard name comes from
+ * `config/auth.ts`. Without a separator that cannot appear in either
+ * half, `("web", "a:b")` and `("web:a", "b")` would collide — and the
+ * collision would grant a permission nobody assigned.
+ */
+export function mapKey(guardName, name) {
+    return `${guardName}\u0000${name}`;
+}
+/** Strip the `bigint`s out, for the cache store. */
+export function serializeMap(map) {
+    return {
+        roles: map.roles.map((role) => ({
+            id: String(role.id),
+            name: role.name,
+            guardName: role.guardName,
+            permissionIds: role.permissionIds.map(String),
+        })),
+        permissions: map.permissions.map((permission) => ({
+            id: String(permission.id),
+            name: permission.name,
+            guardName: permission.guardName,
+        })),
+    };
+}
+/** Put the `bigint`s back, and build the lookup indexes. */
+export function deserializeMap(serialized) {
+    const roles = serialized.roles.map((role) => ({
+        id: BigInt(role.id),
+        name: role.name,
+        guardName: role.guardName,
+        permissionIds: role.permissionIds.map(BigInt),
+    }));
+    const permissions = serialized.permissions.map((permission) => ({
+        id: BigInt(permission.id),
+        name: permission.name,
+        guardName: permission.guardName,
+    }));
+    return buildMap(roles, permissions);
+}
+/** Assemble a map and its indexes from freshly-read rows. */
+export function buildMap(roles, permissions) {
+    const roleByName = new Map();
+    const roleById = new Map();
+    const permissionByName = new Map();
+    const permissionById = new Map();
+    for (const role of roles) {
+        roleByName.set(mapKey(role.guardName, role.name), role);
+        roleById.set(role.id, role);
+    }
+    for (const permission of permissions) {
+        permissionByName.set(mapKey(permission.guardName, permission.name), permission);
+        permissionById.set(permission.id, permission);
+    }
+    return { roles, permissions, roleByName, permissionByName, roleById, permissionById };
+}
+//# sourceMappingURL=permission-map.js.map

package/dist/permission-map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-map.js","sourceRoot":"","sources":["../src/permission-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AA4CH;;;;;;;;;GASG;AACH,MAAM,UAAU,MAAM,CAAC,SAAiB,EAAE,IAAY;IACpD,OAAO,GAAG,SAAS,SAAS,IAAI,EAAE,CAAC;AACrC,CAAC;AAED,oDAAoD;AACpD,MAAM,UAAU,YAAY,CAAC,GAAkB;IAC7C,OAAO;QACL,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YAC9B,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;YACnB,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,aAAa,EAAE,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC;SAC9C,CAAC,CAAC;QACH,WAAW,EAAE,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;YAChD,EAAE,EAAE,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC;YACzB,IAAI,EAAE,UAAU,CAAC,IAAI;YACrB,SAAS,EAAE,UAAU,CAAC,SAAS;SAChC,CAAC,CAAC;KACJ,CAAC;AACJ,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,cAAc,CAAC,UAAmC;IAChE,MAAM,KAAK,GAAiB,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC1D,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;QACnB,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,aAAa,EAAE,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC;KAC9C,CAAC,CAAC,CAAC;IAEJ,MAAM,WAAW,GAAuB,UAAU,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;QAClF,EAAE,EAAE,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC;QACzB,IAAI,EAAE,UAAU,CAAC,IAAI;QACrB,SAAS,EAAE,UAAU,CAAC,SAAS;KAChC,CAAC,CAAC,CAAC;IAEJ,OAAO,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;AACtC,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,QAAQ,CAAC,KAAmB,EAAE,WAA+B;IAC3E,MAAM,UAAU,GAAG,IAAI,GAAG,EAAsB,CAAC;IACjD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAsB,CAAC;IAC/C,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAA4B,CAAC;IAC7D,MAAM,cAAc,GAAG,IAAI,GAAG,EAA4B,CAAC;IAE3D,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;QACxD,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IAC9B,CAAC;IAED,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;QACrC,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,SAAS,EAAE,UAAU,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC,CAAC;QAChF,cAAc,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,EAAE,UAAU,CAAC,CAAC;IAChD,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,gBAAgB,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAC;AACxF,CAAC"}

package/dist/permission-registrar.d.ts

@@ -0,0 +1,183 @@
+import type { Application } from "@mahiframework/core";
+import { type Assignee } from "./assignee.js";
+import { type PermissionMap } from "./permission-map.js";
+import { Permission } from "./models/permission.model.js";
+import { Role } from "./models/role.model.js";
+import type { ResolvedPermissionsConfig } from "./permissions-config.js";
+/** Options every name-addressed call accepts. */
+export interface GuardOption {
+    /** The auth guard to scope to. Defaults to config `guard`, then `auth.default`. */
+    guard?: string;
+}
+/** A role named by name, id, or instance. */
+export type RoleRef = string | bigint | Role;
+/** A permission named by name, id, or instance. */
+export type PermissionRef = string | bigint | Permission;
+/** Roles and permissions, their relationships, and who holds them. */
+export declare class PermissionRegistrar {
+    private readonly app;
+    private readonly config;
+    constructor(app: Application, config: ResolvedPermissionsConfig);
+    /**
+     * The guard a call operates on.
+     *
+     * `auth.default` is the last resort rather than the ambient
+     * `currentGuard()`, which would read the guard that authenticated THIS
+     * request. That is tempting and wrong: it throws outside a request
+     * scope (`MissingAuthContextError`), so a queue job or a seeder
+     * assigning a role would crash, and it would make the same
+     * `createRole("admin")` produce a different row depending on who
+     * happened to call it.
+     *
+     * Throws rather than defaulting to `""`: `guard_name` is NOT NULL with
+     * no wildcard, so an unresolvable guard has no safe representation, and
+     * a role stamped with the empty string is a role no check will ever
+     * match.
+     */
+    guardName(options?: GuardOption): string;
+    private defaultGuard;
+    /**
+     * The role/permission map, from cache or the database.
+     *
+     * `remember()` treats `undefined` as its miss sentinel, so the loader
+     * must never return it — this one always returns an object, even for an
+     * app with no roles at all.
+     *
+     * The map crosses the cache boundary serialised (ids as strings): see
+     * `permission-map.ts` for why a `bigint` cannot be cached.
+     */
+    map(): Promise<PermissionMap>;
+    /** Read every role, permission, and role-permission link. Three queries, no joins. */
+    private loadMap;
+    /**
+     * Drop the cached map and every memoised assignment.
+     *
+     * Called by every write here, and by the model-event listeners for
+     * writes that bypass this class (a seeder calling `Role.create()`).
+     * Forgets exactly one key — `@mahiframework/cache` has no tags, so
+     * there is no flush-by-pattern, and `flush()` would take out the app's
+     * entire cache.
+     */
+    forgetCache(): Promise<void>;
+    private cache;
+    /** Create a role. Throws if one already exists with this name for this guard. */
+    createRole(name: string, options?: GuardOption): Promise<Role>;
+    /** Create a permission. Throws if one already exists with this name for this guard. */
+    createPermission(name: string, options?: GuardOption): Promise<Permission>;
+    /** Create a role only if it doesn't exist, returning either way. */
+    findOrCreateRole(name: string, options?: GuardOption): Promise<Role>;
+    /** Create a permission only if it doesn't exist, returning either way. */
+    findOrCreatePermission(name: string, options?: GuardOption): Promise<Permission>;
+    /** The role with this name, or `RoleNotFoundError`. */
+    findRole(name: string, options?: GuardOption): Promise<Role>;
+    /** The permission with this name, or `PermissionNotFoundError`. */
+    findPermission(name: string, options?: GuardOption): Promise<Permission>;
+    /**
+     * Delete a role. Its assignments and permission links go with it, via
+     * the pivots' `cascadeOnDelete` foreign keys.
+     */
+    deleteRole(role: RoleRef, options?: GuardOption): Promise<void>;
+    /** Delete a permission. Its assignments and role links cascade. */
+    deletePermission(permission: PermissionRef, options?: GuardOption): Promise<void>;
+    /** Grant permissions to a role, ignoring any it already has. */
+    givePermissionToRole(role: RoleRef, permissions: PermissionRef | PermissionRef[], options?: GuardOption): Promise<void>;
+    /** Revoke permissions from a role. */
+    revokePermissionFromRole(role: RoleRef, permissions: PermissionRef | PermissionRef[], options?: GuardOption): Promise<void>;
+    /**
+     * Make a role's permissions exactly this list.
+     *
+     * An empty list revokes everything, which is the whole point of a sync
+     * and the one behaviour worth being explicit about: the framework's own
+     * `detach([])` is a deliberate no-op, so a caller passing
+     * `request.input("permissions")` through that API would silently keep
+     * the old set. This writes pivots directly and means what it says.
+     */
+    syncRolePermissions(role: RoleRef, permissions: PermissionRef | PermissionRef[], options?: GuardOption): Promise<void>;
+    /** Assign roles to a subject. Already-held roles are skipped, so this is idempotent. */
+    assignRole(assignee: Assignee, roles: RoleRef | RoleRef[], options?: GuardOption): Promise<void>;
+    /** Remove roles from a subject. */
+    removeRole(assignee: Assignee, roles: RoleRef | RoleRef[], options?: GuardOption): Promise<void>;
+    /** Make a subject's roles exactly this list. An empty list removes all of them. */
+    syncRoles(assignee: Assignee, roles: RoleRef | RoleRef[], options?: GuardOption): Promise<void>;
+    /** Grant permissions to a subject directly, alongside whatever its roles grant. */
+    givePermissionTo(assignee: Assignee, permissions: PermissionRef | PermissionRef[], options?: GuardOption): Promise<void>;
+    /**
+     * Revoke a directly-granted permission.
+     *
+     * Only touches `model_has_permissions`. A permission the subject also
+     * holds through a role survives this call, and `hasPermissionTo()` will
+     * still answer true — which is correct, and the reason
+     * `hasDirectPermission()` exists to tell the two apart.
+     */
+    revokePermissionTo(assignee: Assignee, permissions: PermissionRef | PermissionRef[], options?: GuardOption): Promise<void>;
+    /** Make a subject's direct permissions exactly this list. An empty list removes all of them. */
+    syncPermissions(assignee: Assignee, permissions: PermissionRef | PermissionRef[], options?: GuardOption): Promise<void>;
+    /** Does this subject hold this role? */
+    hasRole(assignee: Assignee, role: string | bigint, options?: GuardOption): Promise<boolean>;
+    /** Does this subject hold at least one of these roles? */
+    hasAnyRole(assignee: Assignee, roles: Array<string | bigint>, options?: GuardOption): Promise<boolean>;
+    /** Does this subject hold every one of these roles? */
+    hasAllRoles(assignee: Assignee, roles: Array<string | bigint>, options?: GuardOption): Promise<boolean>;
+    /**
+     * Does this subject hold this permission, by any route?
+     *
+     * An unknown permission name returns false rather than throwing. This
+     * one is a check, not a write: the gate hook calls it with every
+     * ability string in the app, almost none of which are permissions, so
+     * throwing would turn `can("view-dashboard")` into a 500. The write
+     * methods still throw on an unknown name, which is where a typo
+     * actually matters.
+     */
+    hasPermissionTo(assignee: Assignee, permission: string | bigint, options?: GuardOption): Promise<boolean>;
+    /** Does this subject hold at least one of these permissions, by any route? */
+    hasAnyPermission(assignee: Assignee, permissions: Array<string | bigint>, options?: GuardOption): Promise<boolean>;
+    /** Does this subject hold every one of these permissions, by any route? */
+    hasAllPermissions(assignee: Assignee, permissions: Array<string | bigint>, options?: GuardOption): Promise<boolean>;
+    /** Does this subject hold this permission DIRECTLY, ignoring its roles? */
+    hasDirectPermission(assignee: Assignee, permission: string | bigint, options?: GuardOption): Promise<boolean>;
+    /** This subject's role names, for the resolved guard. */
+    getRoleNames(assignee: Assignee, options?: GuardOption): Promise<Set<string>>;
+    /** Permission names this subject holds via its roles only. */
+    getPermissionsViaRoles(assignee: Assignee, options?: GuardOption): Promise<Set<string>>;
+    /** Permission names granted to this subject directly, ignoring its roles. */
+    getDirectPermissions(assignee: Assignee, options?: GuardOption): Promise<Set<string>>;
+    /** Every permission name this subject holds, by either route. */
+    getAllPermissions(assignee: Assignee, options?: GuardOption): Promise<Set<string>>;
+    /**
+     * One subject's raw assignment ids, memoised per request.
+     *
+     * Two queries, in parallel, and at most once per subject per request.
+     * The memo is what makes the gate hook affordable: it fires on every
+     * authorization check, so a controller with five `can()` calls would
+     * otherwise be ten queries against rows that cannot have changed.
+     */
+    private assignmentsFor;
+    /** The role's name, whether it was named by name or by id. Unknown ids yield a non-matching sentinel. */
+    private roleNameOf;
+    private permissionNameOf;
+    /** Resolve a role reference to its id, throwing on an unknown name. */
+    private roleId;
+    private permissionId;
+    private roleIds;
+    private permissionIds;
+    /**
+     * Insert pivot rows, in chunks, as one multi-row statement each.
+     *
+     * Goes to raw Kysely rather than `QueryBuilder`, whose `insert()` takes
+     * a single row: a per-row loop would turn a 500-permission sync into
+     * 500 round trips. `Role.resolveConnection()` is the handle rather
+     * than a `DatabaseManager` lookup because it swaps in the active
+     * transaction when there is one, which is what makes the `sync*`
+     * methods' delete-then-insert atomic.
+     *
+     * Chunked because pivot writes in this framework do not bound their
+     * parameter count, and a multi-row insert binds one parameter per
+     * column per row — three columns here, so a sync of 12,000 would
+     * exceed SQLite's 32,766-binding ceiling (Postgres' is 65,535) and
+     * fail at the driver rather than anywhere meaningful. 1,000 rows is
+     * 3,000 bindings, well inside every engine. Sequential, since the
+     * chunks all target one table inside one transaction.
+     */
+    private insertChunked;
+}
+//# sourceMappingURL=permission-registrar.d.ts.map

package/dist/permission-registrar.d.ts.map

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