@maestro-js/permissions 1.0.0-alpha.10

package/README.md

@@ -0,0 +1,210 @@
+# @maestro-js/permissions
+
+Subject-action authorization with type-safe action maps and profile-based rule resolution.
+
+## Quick Setup
+
+```ts
+import { Permissions } from '@maestro-js/permissions'
+
+type ActionMap = {
+  Post: ['create', 'read', 'update', 'delete']
+  Comment: ['create', 'read', 'delete']
+  Settings: ['read', 'update']
+}
+type Profile = { role: 'admin' | 'editor' | 'viewer' }
+
+// Define rules with the static driver
+const driver = Permissions.drivers.static<Profile>((profile, allow, forbid) => {
+  if (profile.role === 'admin') {
+    allow('Post', ['create', 'read', 'update', 'delete'])
+    allow('Comment', ['create', 'read', 'delete'])
+    allow('Settings', ['read', 'update'])
+  } else if (profile.role === 'editor') {
+    allow('Post', ['create', 'read', 'update'])
+    allow('Comment', ['create', 'read'])
+    allow('Settings', 'read')
+    forbid('Settings', 'update', 'Editors cannot modify settings')
+  } else {
+    allow('Post', 'read')
+    allow('Comment', 'read')
+    allow('Settings', 'read')
+  }
+})
+
+// Create and register
+const permissions = Permissions.Provider.create<ActionMap, Profile>({ driver })
+Permissions.Provider.register('default', permissions)
+
+// Check permissions via the facade
+Permissions.can({ role: 'editor' }, 'Post', 'create') // true
+```
+
+## Drivers
+
+### Static
+
+The only built-in driver. Accepts a callback that receives the profile and `allow`/`forbid` helpers
+to declaratively define rules:
+
+```ts
+Permissions.drivers.static<Profile>((profile, allow, forbid) => {
+  allow('Post', ['create', 'read'])          // single subject, multiple actions
+  allow(['Post', 'Comment'], 'read')         // multiple subjects, single action
+  forbid('Settings', 'update', 'Not allowed') // forbid with optional reason
+})
+```
+
+- `allow(subject, action)` -- grant access to one or more subjects/actions
+- `forbid(subject, action, reason?)` -- deny access, optionally with a reason string
+
+Rules are evaluated top-to-bottom per call. A `forbid` overrides any prior `allow` for the same
+subject/action pair.
+
+Source: `packages/permissions/src/static-permissions-driver.ts`
+
+## API Reference
+
+### can
+
+```ts
+Permissions.can(profile: P, subject: S, action: M[S][number]): boolean
+```
+Return `true` if the profile is allowed to perform the action on the subject.
+
+```ts
+if (Permissions.can(user, 'Post', 'delete')) {
+  await deletePost(postId)
+}
+```
+
+### cannot
+
+```ts
+Permissions.cannot(profile: P, subject: S, action: M[S][number]): boolean
+```
+Return `true` if the profile is **not** allowed -- the inverse of `can`.
+
+```ts
+if (Permissions.cannot(user, 'Settings', 'update')) {
+  showReadOnlyView()
+}
+```
+
+### gate
+
+```ts
+Permissions.gate(profile: P, subject: S, action: M[S][number]): void
+```
+Assert the profile is allowed. Throws `ForbiddenError` (from `@casl/ability`) on denial.
+
+```ts
+Permissions.gate(user, 'Post', 'update') // throws if denied
+await updatePost(postId, data)
+```
+
+### listRules
+
+```ts
+Permissions.listRules(profile: P): Permissions.Rule[]
+```
+Return the full list of rules generated for the profile. Useful for debugging or serializing
+permissions to a client.
+
+```ts
+const rules = Permissions.listRules({ role: 'editor' })
+// [{ subject: 'Post', action: ['create', 'read', 'update'] }, ...]
+```
+
+## Common Patterns
+
+### Role-based branching
+
+```ts
+function getNavItems(profile: Profile) {
+  const items = [{ label: 'Posts', href: '/posts' }]
+  if (Permissions.can(profile, 'Settings', 'update')) {
+    items.push({ label: 'Settings', href: '/settings' })
+  }
+  return items
+}
+```
+
+### Forbid overrides allow
+
+A `forbid` placed after a broader `allow` removes that specific permission:
+
+```ts
+const driver = Permissions.drivers.static<Profile>((profile, allow, forbid) => {
+  allow('Post', ['create', 'read', 'update', 'delete'])
+  forbid('Post', 'delete') // everyone can CRUD except delete
+})
+```
+
+### Authorization gate in a request handler
+
+```ts
+app.put('/posts/:id', async (req, res) => {
+  try {
+    Permissions.gate(req.user, 'Post', 'update')
+    await updatePost(req.params.id, req.body)
+    res.json({ ok: true })
+  } catch (e) {
+    if (e instanceof ForbiddenError) {
+      res.status(403).json({ error: 'Forbidden' })
+    }
+  }
+})
+```
+
+## Warnings and Gotchas
+
+- **`gate()` throws `ForbiddenError`** -- this is `ForbiddenError` from `@casl/ability`, not a
+  plain `Error`. Import it from `@casl/ability` if you need to catch it specifically.
+- **Forbid order matters** -- `forbid` must come after a broader `allow` for the same
+  subject/action to take effect. A `forbid` with no matching `allow` has no impact.
+- **Rules are re-evaluated per call** -- the driver callback runs on every `can`, `cannot`, `gate`,
+  or `listRules` invocation. There is no internal caching of rule sets.
+
+## Testing
+
+```ts
+import { Permissions } from '@maestro-js/permissions'
+import { test } from 'beartest-js'
+import { expect } from 'expect'
+
+type ActionMap = { Post: ['create', 'read'] }
+type Profile = { role: 'admin' | 'viewer' }
+
+const driver = Permissions.drivers.static<Profile>((profile, allow) => {
+  if (profile.role === 'admin') allow('Post', ['create', 'read'])
+  else allow('Post', 'read')
+})
+const permissions = Permissions.Provider.create<ActionMap, Profile>({ driver })
+
+test('admin can create posts', () => {
+  expect(permissions.can({ role: 'admin' }, 'Post', 'create')).toBe(true)
+})
+
+test('viewer cannot create posts', () => {
+  expect(permissions.cannot({ role: 'viewer' }, 'Post', 'create')).toBe(true)
+})
+```
+
+Run tests:
+
+```bash
+pnpm --filter @maestro-js/permissions test
+cd packages/permissions && npx beartest ./tests/permissions.test.ts
+```
+
+## Cross-Package Integration
+
+- **Depends on**: `@maestro-js/service-registry` (Provider pattern foundation),
+  `@casl/ability` (rule engine and `ForbiddenError`)
+
+## Key Source Files
+
+- `packages/permissions/src/index.ts` -- main export, Provider pattern, `create()`, type namespace
+- `packages/permissions/src/static-permissions-driver.ts` -- static driver with `allow`/`forbid` helpers
+- `packages/permissions/tests/permissions.test.ts` -- runtime and type-level tests

package/dist/index.d.ts

@@ -0,0 +1,126 @@
+import { CustomErrors } from '@maestro-js/custom-errors';
+
+interface Rule {
+    subject: string | string[];
+    action: string | string[];
+    inverted?: boolean;
+    reason?: string;
+}
+interface Driver<P> {
+    listRules: (profile: P) => Rule[];
+}
+type AllowFn<M extends Record<string, string[]> = Record<string, string[]>> = <S extends keyof M>(subject: S, action: (M[S][number] | M[S][number][]) | 'manage') => void;
+type ForbidFn<M extends Record<string, string[]> = Record<string, string[]>> = <S extends keyof M>(subject: S, action: M[S][number] | M[S][number][], reason?: string) => void;
+declare function staticPermissionsDriver<M extends Record<string, string[]> = Record<string, string[]>, P = unknown>(callback: (profile: P, allow: AllowFn<M>, forbid: ForbidFn) => void): Driver<P>;
+
+declare function create<M extends Record<string, string[]> = Record<string, string[]>, P = unknown>(config: Permissions.Internal.Config<P>): Permissions.Internal.Service<M, P>;
+declare function provider<Key extends Permissions.Provider.Key>(key: Key): Permissions.PermissionsService<Key>;
+declare const PermissionsBase: {
+    Provider: {
+        create: typeof create;
+        register: (name: Permissions.Provider.Key, item: Permissions.AnyPermissionsService) => void;
+    };
+    drivers: {
+        static: typeof staticPermissionsDriver;
+    };
+    provider: typeof provider;
+    PermissionsError: CustomErrors.CustomErrorConstructor<{
+        action: string;
+        subject: string;
+    }, {
+        action: string;
+        subject: string;
+    }, "forbidden">;
+};
+type KeysWithFallback = keyof Permissions.Provider.Keys extends never ? {
+    default: {
+        ActionMap: Record<string, string[]>;
+        Profile: unknown;
+    };
+} : Permissions.Provider.Keys;
+/**
+ * Subject-action authorization with type-safe action maps and profile-based rule resolution.
+ * Call methods directly on the default instance, or use `Permissions.Provider.create()` for named instances.
+ */
+declare const Permissions: Permissions.PermissionsService<'default'> & typeof PermissionsBase;
+/**
+ * Subject-action authorization with type-safe action maps and profile-based rule resolution.
+ *
+ * Generic `ActionMap` and `Profile` types constrain subjects, actions, and profile shapes at
+ * compile time. Rules are defined declaratively via the static driver's `allow`/`forbid`
+ * helpers and evaluated per call using CASL's `PureAbility` engine.
+ *
+ * @example
+ * ```ts
+ * import { Permissions } from '@maestro-js/permissions'
+ *
+ * type ActionMap = { Post: ['create', 'read', 'update', 'delete'] }
+ * type Profile = { role: 'admin' | 'viewer' }
+ *
+ * const driver = Permissions.drivers.static<Profile>((profile, allow) => {
+ *   if (profile.role === 'admin') allow('Post', ['create', 'read', 'update', 'delete'])
+ *   else allow('Post', 'read')
+ * })
+ *
+ * const permissions = Permissions.Provider.create<ActionMap, Profile>({ driver })
+ * Permissions.Provider.register('default', permissions)
+ *
+ * Permissions.can({ role: 'admin' }, 'Post', 'delete')  // true
+ * Permissions.gate({ role: 'viewer' }, 'Post', 'delete') // throws ForbiddenError
+ * ```
+ */
+declare namespace Permissions {
+    type PermissionsService<ProviderKey extends Provider.Key = 'default'> = Internal.Service<KeysWithFallback[ProviderKey]['ActionMap'], KeysWithFallback[ProviderKey]['Profile']>;
+    type AnyPermissionsService = Internal.Service<any, any>;
+    type PermissionsServiceConfig<ProviderKey extends Provider.Key = 'default'> = Internal.Config<KeysWithFallback[ProviderKey]['Profile']>;
+    type Subject<ProviderKey extends Provider.Key = 'default'> = keyof KeysWithFallback[ProviderKey]['ActionMap'] & string;
+    type Action<ProviderKey extends Provider.Key = 'default'> = KeysWithFallback[ProviderKey]['ActionMap'][Subject<ProviderKey>][number];
+    /** A single permission rule — `inverted: true` marks a forbid rule */
+    interface Rule {
+        subject: string | string[];
+        action: string | string[];
+        inverted?: boolean;
+        reason?: string;
+    }
+    /**
+     * Core permission operations for checking and enforcing access control.
+     *
+     * Use `can`/`cannot` for boolean checks and `gate` to throw on unauthorized access.
+     * Rules are built from the configured driver each time a method is called.
+     *
+     * Returned by `Permissions.Provider.create()` or resolved via `Permissions.provider()`.
+     *
+     * @example
+     * ```ts
+     * permissions.can({ role: 'editor' }, 'Post', 'create')    // true
+     * permissions.cannot({ role: 'viewer' }, 'Post', 'delete') // true
+     * permissions.gate({ role: 'admin' }, 'Settings', 'update') // void (allowed)
+     * ```
+     */
+    namespace Internal {
+        interface Service<M extends Record<string, string[]>, P> {
+            /** Return `true` if the profile is allowed to perform the action on the subject */
+            can<S extends keyof M & string>(profile: P, subject: S, action: M[S][number]): boolean;
+            /** Return `true` if the profile is not allowed — the inverse of `can` */
+            cannot<S extends keyof M & string>(profile: P, subject: S, action: M[S][number]): boolean;
+            /** Assert the profile is allowed — throws `ForbiddenError` on denial */
+            gate<S extends keyof M & string>(profile: P, subject: S, action: M[S][number]): void;
+            /** Return the full list of rules generated for the profile */
+            listRules(profile: P): Permissions.Rule[];
+        }
+        interface Config<P> {
+            driver: Internal.Driver<P>;
+        }
+        interface Driver<P> {
+            /** Return the full list of rules generated for the profile */
+            listRules: (profile: P) => Permissions.Rule[];
+        }
+    }
+    namespace Provider {
+        type Key = keyof KeysWithFallback;
+        interface Keys {
+        }
+    }
+}
+
+export { Permissions };

package/dist/index.js

@@ -0,0 +1,82 @@
+// src/index.ts
+import { PureAbility } from "@casl/ability";
+import { CustomErrors } from "@maestro-js/custom-errors";
+import { ServiceRegistry } from "@maestro-js/service-registry";
+
+// src/static-permissions-driver.ts
+function staticPermissionsDriver(callback) {
+  return {
+    listRules(profile) {
+      const rules = [];
+      const allow = (subject, action) => {
+        rules.push({ subject, action });
+      };
+      const forbid = (subject, action, reason) => {
+        rules.push({ subject, action, inverted: true, ...reason !== void 0 && { reason } });
+      };
+      callback(profile, allow, forbid);
+      return rules;
+    }
+  };
+}
+
+// src/index.ts
+var PermissionsError = CustomErrors.create({
+  name: "PermissionsError",
+  message: (input) => `Cannot execute "${input.action}" on "${input.subject}"`,
+  additionalAttributes: (input) => ({
+    action: input.action,
+    subject: input.subject
+  }),
+  httpStatusCode: "forbidden"
+});
+function create(config) {
+  const driver = config.driver;
+  function buildAbility(profile) {
+    const rules = driver.listRules(profile);
+    return new PureAbility(rules);
+  }
+  function can(profile, subject, action) {
+    const ability = buildAbility(profile);
+    return ability.can(action, subject);
+  }
+  function cannot(profile, subject, action) {
+    const ability = buildAbility(profile);
+    return ability.cannot(action, subject);
+  }
+  function gate(profile, subject, action) {
+    const ability = buildAbility(profile);
+    if (ability.cannot(action, subject)) {
+      throw new PermissionsError({ action, subject });
+    }
+  }
+  function listRules(profile) {
+    return driver.listRules(profile);
+  }
+  return { can, cannot, gate, listRules };
+}
+var registry = ServiceRegistry.createRegistry(
+  ServiceRegistry.proxyFunctionsForObject
+);
+var Provider = {
+  create,
+  register: registry.register
+};
+function provider(key) {
+  const service = registry.resolve(key);
+  return { can: service.can, cannot: service.cannot, gate: service.gate, listRules: service.listRules };
+}
+var PermissionsBase = {
+  Provider,
+  drivers: { static: staticPermissionsDriver },
+  provider,
+  PermissionsError
+};
+var Permissions = {
+  ...PermissionsBase,
+  PermissionsError,
+  ...provider("default")
+};
+export {
+  Permissions
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@maestro-js/permissions",
+  "description": "Subject-action authorization with type-safe action maps and profile-based rule resolution. Use when you need role-based access control, permission checks (can/cannot), or authorization gates that throw on denial. Provides a static driver for declarative allow/forbid rule definitions. Built on CASL.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "version": "1.0.0-alpha.10",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@casl/ability": "^6.7.3",
+    "@maestro-js/custom-errors": "1.0.0-alpha.10",
+    "@maestro-js/service-registry": "1.0.0-alpha.10"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.11"
+  },
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "repository": "https://github.com/Marcato-Partners/maestro-js",
+  "scripts": {
+    "build": "tsup --config ../../tsup.config.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "beartest ./tests/**/*",
+    "format": "prettier --write src/ tests/",
+    "lint": "prettier --check src/ tests/"
+  }
+}