@mahiframework/permissions 0.1.4

package/dist/relations.js

@@ -0,0 +1,62 @@
+import { morphToMany } from "@mahiframework/database";
+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 function rolesRelation() {
+    return morphToMany(() => Role, {
+        pivotTable: "model_has_roles",
+        morphType: "model_type",
+        morphId: "model_id",
+        relatedPivotKey: "role_id",
+    });
+}
+/**
+ * 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 function permissionsRelation() {
+    return morphToMany(() => Permission, {
+        pivotTable: "model_has_permissions",
+        morphType: "model_type",
+        morphId: "model_id",
+        relatedPivotKey: "permission_id",
+    });
+}
+//# sourceMappingURL=relations.js.map

package/dist/relations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relations.js","sourceRoot":"","sources":["../src/relations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAC1D,OAAO,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO,WAAW,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE;QAC7B,UAAU,EAAE,iBAAiB;QAC7B,SAAS,EAAE,YAAY;QACvB,OAAO,EAAE,UAAU;QACnB,eAAe,EAAE,SAAS;KAC3B,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO,WAAW,CAAC,GAAG,EAAE,CAAC,UAAU,EAAE;QACnC,UAAU,EAAE,uBAAuB;QACnC,SAAS,EAAE,YAAY;QACvB,OAAO,EAAE,UAAU;QACnB,eAAe,EAAE,eAAe;KACjC,CAAC,CAAC;AACL,CAAC"}

package/dist/request-cache.d.ts

@@ -0,0 +1,50 @@
+/**
+ * A per-request memo of each subject's raw assignments.
+ *
+ * This exists because of how the gate hook works, not as a general
+ * optimisation. `GateRegistry.before()` callbacks run on EVERY
+ * authorization check, so a controller doing five `can()` calls would
+ * otherwise issue ten queries (roles and direct permissions, twice per
+ * call) against rows that cannot have changed mid-request unless this
+ * request changed them.
+ *
+ * Scoped rather than global for the obvious reason: a long-lived worker
+ * process would otherwise serve one request's answers to the next, and
+ * "why does this user still have admin" is not a bug anybody enjoys.
+ *
+ * The provider's `middleware()` pipe opens a scope per request. Outside
+ * one, `assignmentMemo()` returns null and every read goes to the
+ * database — correct by default, since a queue job or a CLI command has
+ * no natural boundary at which the memo should expire. A job that wants
+ * one wraps itself in `withPermissionCache()`.
+ *
+ * Writes through the registrar clear the memo rather than patching it:
+ * patching means keeping two representations in step, and clearing costs
+ * one query on the next check.
+ */
+export interface AssignmentRecord {
+    roleIds: bigint[];
+    permissionIds: bigint[];
+}
+/** Run `fn` inside a memo scope. Called once per request by the provider's pipe. */
+export declare function runWithPermissionCache<T>(fn: () => T): T;
+/**
+ * Open a memo scope around a job, command, or test.
+ *
+ * Async-returning so a caller cannot forget to await it, and so the scope
+ * genuinely covers the whole callback rather than just its synchronous
+ * prefix.
+ */
+export declare function withPermissionCache<T>(callback: () => T | Promise<T>): Promise<T>;
+/** The active memo, or null outside a scope. */
+export declare function assignmentMemo(): Map<string, AssignmentRecord> | null;
+/**
+ * Drop memoised assignments.
+ *
+ * With no argument, clears everything: a role's permissions changing
+ * affects every subject holding it, and the registrar has no index from
+ * role to subject. Pass a key to drop just one subject, which is what an
+ * assignment write does.
+ */
+export declare function forgetMemoisedAssignments(cacheKey?: string): void;
+//# sourceMappingURL=request-cache.d.ts.map

package/dist/request-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-cache.d.ts","sourceRoot":"","sources":["../src/request-cache.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAID,oFAAoF;AACpF,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAExD;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAEjF;AAED,gDAAgD;AAChD,wBAAgB,cAAc,IAAI,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAAG,IAAI,CAErE;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAcjE"}

package/dist/request-cache.js

@@ -0,0 +1,40 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const storage = new AsyncLocalStorage();
+/** Run `fn` inside a memo scope. Called once per request by the provider's pipe. */
+export function runWithPermissionCache(fn) {
+    return storage.run(new Map(), fn);
+}
+/**
+ * Open a memo scope around a job, command, or test.
+ *
+ * Async-returning so a caller cannot forget to await it, and so the scope
+ * genuinely covers the whole callback rather than just its synchronous
+ * prefix.
+ */
+export function withPermissionCache(callback) {
+    return storage.run(new Map(), async () => callback());
+}
+/** The active memo, or null outside a scope. */
+export function assignmentMemo() {
+    return storage.getStore() ?? null;
+}
+/**
+ * Drop memoised assignments.
+ *
+ * With no argument, clears everything: a role's permissions changing
+ * affects every subject holding it, and the registrar has no index from
+ * role to subject. Pass a key to drop just one subject, which is what an
+ * assignment write does.
+ */
+export function forgetMemoisedAssignments(cacheKey) {
+    const memo = storage.getStore();
+    if (memo === undefined) {
+        return;
+    }
+    if (cacheKey === undefined) {
+        memo.clear();
+        return;
+    }
+    memo.delete(cacheKey);
+}
+//# sourceMappingURL=request-cache.js.map

package/dist/request-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-cache.js","sourceRoot":"","sources":["../src/request-cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AA+BrD,MAAM,OAAO,GAAG,IAAI,iBAAiB,EAAiC,CAAC;AAEvE,oFAAoF;AACpF,MAAM,UAAU,sBAAsB,CAAI,EAAW;IACnD,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,EAA4B,EAAE,EAAE,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAI,QAA8B;IACnE,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,EAA4B,EAAE,KAAK,IAAI,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC;AAClF,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,cAAc;IAC5B,OAAO,OAAO,CAAC,QAAQ,EAAE,IAAI,IAAI,CAAC;AACpC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,yBAAyB,CAAC,QAAiB;IACzD,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAEhC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO;IACT,CAAC;IAED,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,IAAI,CAAC,KAAK,EAAE,CAAC;QAEb,OAAO;IACT,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;AACxB,CAAC"}

package/dist/tokens.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The `PermissionRegistrar` singleton.
+ *
+ * NOT in `@mahiframework/core`'s `well-known-tokens.ts`. That file is
+ * explicitly for tokens referenced ACROSS package boundaries by packages
+ * that deliberately avoid a compile-time dependency; nothing outside this
+ * package resolves this one by string. A local literal is correct until
+ * that changes.
+ *
+ * A separate module from the provider so the facade and the middleware
+ * can import the token without importing the provider, which would be a
+ * cycle.
+ */
+export declare const PERMISSIONS_TOKEN = "permissions";
+//# sourceMappingURL=tokens.d.ts.map

package/dist/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB,gBAAgB,CAAC"}

package/dist/tokens.js

@@ -0,0 +1,15 @@
+/**
+ * The `PermissionRegistrar` singleton.
+ *
+ * NOT in `@mahiframework/core`'s `well-known-tokens.ts`. That file is
+ * explicitly for tokens referenced ACROSS package boundaries by packages
+ * that deliberately avoid a compile-time dependency; nothing outside this
+ * package resolves this one by string. A local literal is correct until
+ * that changes.
+ *
+ * A separate module from the provider so the facade and the middleware
+ * can import the token without importing the provider, which would be a
+ * cycle.
+ */
+export const PERMISSIONS_TOKEN = "permissions";
+//# sourceMappingURL=tokens.js.map

package/dist/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,aAAa,CAAC"}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@mahiframework/permissions",
+  "version": "0.1.4",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "@mahiframework/auth": "0.1.4",
+    "@mahiframework/cli": "0.1.4",
+    "@mahiframework/core": "0.1.4",
+    "@mahiframework/database": "0.1.4",
+    "@mahiframework/events": "0.1.4",
+    "@mahiframework/datetime": "0.1.4",
+    "@mahiframework/http": "0.1.4",
+    "@mahiframework/facades": "0.1.4",
+    "@mahiframework/cache": "0.1.4",
+    "@mahiframework/authorization": "0.1.4",
+    "@mahiframework/snowflake": "0.1.4"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2",
+    "vite": "^8.0.0",
+    "vitest": "^4.1.11"
+  },
+  "license": "MIT",
+  "author": "Bradie Tilley",
+  "homepage": "https://github.com/mahiframework/mahi#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mahiframework/mahi.git",
+    "directory": "framework/permissions"
+  },
+  "bugs": {
+    "url": "https://github.com/mahiframework/mahi/issues"
+  },
+  "engines": {
+    "node": ">=26"
+  },
+  "sideEffects": false,
+  "description": "Permissions — roles, permissions, and cached authorization checks for Mahi.",
+  "keywords": [
+    "mahi",
+    "permissions",
+    "roles",
+    "authorization",
+    "acl"
+  ],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b && node ../../scripts/prune-dist.mjs",
+    "typecheck": "tsc -b && tsc -p tsconfig.test.json",
+    "lint": "eslint src tests",
+    "test": "vitest run"
+  }
+}