@auth-gate/testing 0.9.3 → 0.11.0

package/dist/rbac/index.d.cts

@@ -0,0 +1,167 @@
+import { RbacConfig, ResourceConfig, RoleConfig } from '@auth-gate/rbac';
+export { GrantValue, RbacConfig, ResourceConfig, RoleConfig } from '@auth-gate/rbac';
+
+/**
+ * Create a minimal valid RbacConfig for testing.
+ *
+ * Defaults:
+ * - Resource `documents` with actions `read`, `write`, `delete`
+ * - Role `admin` with all three grants
+ * - Role `viewer` with `read` only, marked as `isDefault`
+ *
+ * Pass `overrides` to merge/replace specific keys.
+ */
+declare function createTestRbacConfig(overrides?: Partial<RbacConfig>): RbacConfig;
+/**
+ * Create a single-resource record for use in test configs.
+ *
+ * @param key     - The resource key (e.g. `"billing"`).
+ * @param actions - Array of action strings (e.g. `["read", "manage"]`).
+ * @param overrides - Additional ResourceConfig fields (e.g. `scopes`).
+ * @returns `Record<string, ResourceConfig>` keyed by `key`.
+ *
+ * @example
+ * ```ts
+ * const config = createTestRbacConfig({
+ *   resources: {
+ *     ...createTestResource("billing", ["read", "manage"]),
+ *     ...createTestResource("users", ["read", "invite", "remove"]),
+ *   },
+ * });
+ * ```
+ */
+declare function createTestResource(key: string, actions: string[], overrides?: Partial<ResourceConfig>): Record<string, ResourceConfig>;
+/**
+ * Create a single-role record for use in test configs.
+ *
+ * @param key    - The role key (e.g. `"editor"`).
+ * @param name   - Human-readable display name (e.g. `"Editor"`).
+ * @param grants - The grants matrix.
+ * @param overrides - Additional RoleConfig fields (e.g. `inherits`, `isDefault`).
+ * @returns `Record<string, RoleConfig>` keyed by `key`.
+ *
+ * @example
+ * ```ts
+ * const config = createTestRbacConfig({
+ *   roles: {
+ *     ...createTestRole("editor", "Editor", {
+ *       documents: { read: true, write: true },
+ *     }),
+ *   },
+ * });
+ * ```
+ */
+declare function createTestRole(key: string, name: string, grants: Record<string, Record<string, true | string | {
+    when: string;
+    scope?: string;
+}>>, overrides?: Partial<Omit<RoleConfig, "name" | "grants">>): Record<string, RoleConfig>;
+
+/**
+ * In-memory RBAC permission checker for testing.
+ *
+ * Resolves permissions from an RbacConfig, including role inheritance.
+ * All grant values (`true`, scope string, or conditional `{ when, scope }`)
+ * are treated as "granted" for the purpose of boolean permission checks.
+ *
+ * @example
+ * ```ts
+ * import { defineRbac } from "@auth-gate/rbac";
+ * import { RbacChecker } from "@auth-gate/testing/rbac";
+ *
+ * const rbac = defineRbac({ ... });
+ * const checker = new RbacChecker(rbac);
+ *
+ * checker.hasPermission("admin", "documents:read"); // true
+ * checker.getPermissions("viewer"); // Set { "documents:read" }
+ * checker.getRolesWithPermission("documents:delete"); // ["admin"]
+ * ```
+ */
+declare class RbacChecker {
+    private readonly config;
+    /**
+     * @param input - Either a plain `RbacConfig` object, or a `TypedRbac`
+     *   instance (from `defineRbac()`) which exposes `_config`.
+     */
+    constructor(input: RbacConfig | {
+        _config: RbacConfig;
+    });
+    /**
+     * Check whether a role has a specific permission.
+     *
+     * @param roleKey    - The role key (e.g. `"admin"`).
+     * @param permission - A `"resource:action"` string (e.g. `"documents:read"`).
+     * @returns `true` if the role (or any ancestor via inheritance) grants the permission.
+     */
+    hasPermission(roleKey: string, permission: string): boolean;
+    /**
+     * Collect all permissions for a role, including inherited ones.
+     *
+     * @param roleKey - The role key.
+     * @returns A `Set<string>` of `"resource:action"` strings.
+     */
+    getPermissions(roleKey: string): Set<string>;
+    /**
+     * Find all roles that grant a specific permission.
+     *
+     * @param permission - A `"resource:action"` string.
+     * @returns Array of role keys that have the permission (directly or via inheritance).
+     */
+    getRolesWithPermission(permission: string): string[];
+    /**
+     * Recursively collect permissions for a role, following `inherits` chains.
+     * Uses a `visited` set to prevent infinite loops from circular inheritance.
+     */
+    private collectPermissions;
+}
+
+/**
+ * Assert that a role has a specific permission. Throws with a descriptive
+ * error message listing the role's actual permissions if the assertion fails.
+ *
+ * @param rbac       - An `RbacConfig` or `TypedRbac` instance.
+ * @param roleKey    - The role key to check.
+ * @param permission - The `"resource:action"` permission string expected.
+ *
+ * @example
+ * ```ts
+ * expectPermission(config, "admin", "documents:write");
+ * ```
+ */
+declare function expectPermission(rbac: RbacConfig | {
+    _config: RbacConfig;
+}, roleKey: string, permission: string): void;
+/**
+ * Assert that a role does NOT have a specific permission. Throws if the
+ * role has the permission.
+ *
+ * @param rbac       - An `RbacConfig` or `TypedRbac` instance.
+ * @param roleKey    - The role key to check.
+ * @param permission - The `"resource:action"` permission string that must be absent.
+ *
+ * @example
+ * ```ts
+ * expectNoPermission(config, "viewer", "documents:delete");
+ * ```
+ */
+declare function expectNoPermission(rbac: RbacConfig | {
+    _config: RbacConfig;
+}, roleKey: string, permission: string): void;
+/**
+ * Assert that a role has exactly the specified set of permissions -- no more,
+ * no less. Throws with details about missing and extra permissions if the
+ * sets do not match.
+ *
+ * @param rbac     - An `RbacConfig` or `TypedRbac` instance.
+ * @param roleKey  - The role key to check.
+ * @param expected - The exact set of `"resource:action"` strings expected.
+ *
+ * @example
+ * ```ts
+ * expectRolePermissions(config, "viewer", ["documents:read"]);
+ * ```
+ */
+declare function expectRolePermissions(rbac: RbacConfig | {
+    _config: RbacConfig;
+}, roleKey: string, expected: string[]): void;
+
+export { RbacChecker, createTestRbacConfig, createTestResource, createTestRole, expectNoPermission, expectPermission, expectRolePermissions };

package/dist/rbac/index.d.ts

@@ -0,0 +1,167 @@
+import { RbacConfig, ResourceConfig, RoleConfig } from '@auth-gate/rbac';
+export { GrantValue, RbacConfig, ResourceConfig, RoleConfig } from '@auth-gate/rbac';
+
+/**
+ * Create a minimal valid RbacConfig for testing.
+ *
+ * Defaults:
+ * - Resource `documents` with actions `read`, `write`, `delete`
+ * - Role `admin` with all three grants
+ * - Role `viewer` with `read` only, marked as `isDefault`
+ *
+ * Pass `overrides` to merge/replace specific keys.
+ */
+declare function createTestRbacConfig(overrides?: Partial<RbacConfig>): RbacConfig;
+/**
+ * Create a single-resource record for use in test configs.
+ *
+ * @param key     - The resource key (e.g. `"billing"`).
+ * @param actions - Array of action strings (e.g. `["read", "manage"]`).
+ * @param overrides - Additional ResourceConfig fields (e.g. `scopes`).
+ * @returns `Record<string, ResourceConfig>` keyed by `key`.
+ *
+ * @example
+ * ```ts
+ * const config = createTestRbacConfig({
+ *   resources: {
+ *     ...createTestResource("billing", ["read", "manage"]),
+ *     ...createTestResource("users", ["read", "invite", "remove"]),
+ *   },
+ * });
+ * ```
+ */
+declare function createTestResource(key: string, actions: string[], overrides?: Partial<ResourceConfig>): Record<string, ResourceConfig>;
+/**
+ * Create a single-role record for use in test configs.
+ *
+ * @param key    - The role key (e.g. `"editor"`).
+ * @param name   - Human-readable display name (e.g. `"Editor"`).
+ * @param grants - The grants matrix.
+ * @param overrides - Additional RoleConfig fields (e.g. `inherits`, `isDefault`).
+ * @returns `Record<string, RoleConfig>` keyed by `key`.
+ *
+ * @example
+ * ```ts
+ * const config = createTestRbacConfig({
+ *   roles: {
+ *     ...createTestRole("editor", "Editor", {
+ *       documents: { read: true, write: true },
+ *     }),
+ *   },
+ * });
+ * ```
+ */
+declare function createTestRole(key: string, name: string, grants: Record<string, Record<string, true | string | {
+    when: string;
+    scope?: string;
+}>>, overrides?: Partial<Omit<RoleConfig, "name" | "grants">>): Record<string, RoleConfig>;
+
+/**
+ * In-memory RBAC permission checker for testing.
+ *
+ * Resolves permissions from an RbacConfig, including role inheritance.
+ * All grant values (`true`, scope string, or conditional `{ when, scope }`)
+ * are treated as "granted" for the purpose of boolean permission checks.
+ *
+ * @example
+ * ```ts
+ * import { defineRbac } from "@auth-gate/rbac";
+ * import { RbacChecker } from "@auth-gate/testing/rbac";
+ *
+ * const rbac = defineRbac({ ... });
+ * const checker = new RbacChecker(rbac);
+ *
+ * checker.hasPermission("admin", "documents:read"); // true
+ * checker.getPermissions("viewer"); // Set { "documents:read" }
+ * checker.getRolesWithPermission("documents:delete"); // ["admin"]
+ * ```
+ */
+declare class RbacChecker {
+    private readonly config;
+    /**
+     * @param input - Either a plain `RbacConfig` object, or a `TypedRbac`
+     *   instance (from `defineRbac()`) which exposes `_config`.
+     */
+    constructor(input: RbacConfig | {
+        _config: RbacConfig;
+    });
+    /**
+     * Check whether a role has a specific permission.
+     *
+     * @param roleKey    - The role key (e.g. `"admin"`).
+     * @param permission - A `"resource:action"` string (e.g. `"documents:read"`).
+     * @returns `true` if the role (or any ancestor via inheritance) grants the permission.
+     */
+    hasPermission(roleKey: string, permission: string): boolean;
+    /**
+     * Collect all permissions for a role, including inherited ones.
+     *
+     * @param roleKey - The role key.
+     * @returns A `Set<string>` of `"resource:action"` strings.
+     */
+    getPermissions(roleKey: string): Set<string>;
+    /**
+     * Find all roles that grant a specific permission.
+     *
+     * @param permission - A `"resource:action"` string.
+     * @returns Array of role keys that have the permission (directly or via inheritance).
+     */
+    getRolesWithPermission(permission: string): string[];
+    /**
+     * Recursively collect permissions for a role, following `inherits` chains.
+     * Uses a `visited` set to prevent infinite loops from circular inheritance.
+     */
+    private collectPermissions;
+}
+
+/**
+ * Assert that a role has a specific permission. Throws with a descriptive
+ * error message listing the role's actual permissions if the assertion fails.
+ *
+ * @param rbac       - An `RbacConfig` or `TypedRbac` instance.
+ * @param roleKey    - The role key to check.
+ * @param permission - The `"resource:action"` permission string expected.
+ *
+ * @example
+ * ```ts
+ * expectPermission(config, "admin", "documents:write");
+ * ```
+ */
+declare function expectPermission(rbac: RbacConfig | {
+    _config: RbacConfig;
+}, roleKey: string, permission: string): void;
+/**
+ * Assert that a role does NOT have a specific permission. Throws if the
+ * role has the permission.
+ *
+ * @param rbac       - An `RbacConfig` or `TypedRbac` instance.
+ * @param roleKey    - The role key to check.
+ * @param permission - The `"resource:action"` permission string that must be absent.
+ *
+ * @example
+ * ```ts
+ * expectNoPermission(config, "viewer", "documents:delete");
+ * ```
+ */
+declare function expectNoPermission(rbac: RbacConfig | {
+    _config: RbacConfig;
+}, roleKey: string, permission: string): void;
+/**
+ * Assert that a role has exactly the specified set of permissions -- no more,
+ * no less. Throws with details about missing and extra permissions if the
+ * sets do not match.
+ *
+ * @param rbac     - An `RbacConfig` or `TypedRbac` instance.
+ * @param roleKey  - The role key to check.
+ * @param expected - The exact set of `"resource:action"` strings expected.
+ *
+ * @example
+ * ```ts
+ * expectRolePermissions(config, "viewer", ["documents:read"]);
+ * ```
+ */
+declare function expectRolePermissions(rbac: RbacConfig | {
+    _config: RbacConfig;
+}, roleKey: string, expected: string[]): void;
+
+export { RbacChecker, createTestRbacConfig, createTestResource, createTestRole, expectNoPermission, expectPermission, expectRolePermissions };

package/dist/rbac/index.mjs

@@ -0,0 +1,180 @@
+import {
+  __spreadValues
+} from "../chunk-MBTDPSN5.mjs";
+
+// src/rbac/builders.ts
+function createTestRbacConfig(overrides) {
+  return __spreadValues({
+    resources: {
+      documents: { actions: ["read", "write", "delete"] }
+    },
+    roles: {
+      admin: {
+        name: "Admin",
+        grants: {
+          documents: { read: true, write: true, delete: true }
+        }
+      },
+      viewer: {
+        name: "Viewer",
+        isDefault: true,
+        grants: {
+          documents: { read: true }
+        }
+      }
+    }
+  }, overrides);
+}
+function createTestResource(key, actions, overrides) {
+  return {
+    [key]: __spreadValues({
+      actions
+    }, overrides)
+  };
+}
+function createTestRole(key, name, grants, overrides) {
+  return {
+    [key]: __spreadValues({
+      name,
+      grants
+    }, overrides)
+  };
+}
+
+// src/rbac/checker.ts
+var RbacChecker = class {
+  /**
+   * @param input - Either a plain `RbacConfig` object, or a `TypedRbac`
+   *   instance (from `defineRbac()`) which exposes `_config`.
+   */
+  constructor(input) {
+    this.config = "_config" in input ? input._config : input;
+  }
+  /**
+   * Check whether a role has a specific permission.
+   *
+   * @param roleKey    - The role key (e.g. `"admin"`).
+   * @param permission - A `"resource:action"` string (e.g. `"documents:read"`).
+   * @returns `true` if the role (or any ancestor via inheritance) grants the permission.
+   */
+  hasPermission(roleKey, permission) {
+    return this.getPermissions(roleKey).has(permission);
+  }
+  /**
+   * Collect all permissions for a role, including inherited ones.
+   *
+   * @param roleKey - The role key.
+   * @returns A `Set<string>` of `"resource:action"` strings.
+   */
+  getPermissions(roleKey) {
+    const permissions = /* @__PURE__ */ new Set();
+    this.collectPermissions(roleKey, permissions, /* @__PURE__ */ new Set());
+    return permissions;
+  }
+  /**
+   * Find all roles that grant a specific permission.
+   *
+   * @param permission - A `"resource:action"` string.
+   * @returns Array of role keys that have the permission (directly or via inheritance).
+   */
+  getRolesWithPermission(permission) {
+    const result = [];
+    for (const roleKey of Object.keys(this.config.roles)) {
+      if (this.hasPermission(roleKey, permission)) {
+        result.push(roleKey);
+      }
+    }
+    return result;
+  }
+  /**
+   * Recursively collect permissions for a role, following `inherits` chains.
+   * Uses a `visited` set to prevent infinite loops from circular inheritance.
+   */
+  collectPermissions(roleKey, permissions, visited) {
+    if (visited.has(roleKey)) return;
+    visited.add(roleKey);
+    const role = this.config.roles[roleKey];
+    if (!role) return;
+    for (const [resource, actions] of Object.entries(role.grants)) {
+      for (const [action, value] of Object.entries(
+        actions
+      )) {
+        if (isGranted(value)) {
+          permissions.add(`${resource}:${action}`);
+        }
+      }
+    }
+    if (role.inherits) {
+      for (const parentKey of role.inherits) {
+        this.collectPermissions(parentKey, permissions, visited);
+      }
+    }
+  }
+};
+function isGranted(value) {
+  if (value === true) return true;
+  if (typeof value === "string") return true;
+  if (typeof value === "object" && value !== null && "when" in value) return true;
+  return false;
+}
+
+// src/rbac/assertions.ts
+function toChecker(input) {
+  return new RbacChecker(input);
+}
+function expectPermission(rbac, roleKey, permission) {
+  const checker = toChecker(rbac);
+  if (!checker.hasPermission(roleKey, permission)) {
+    const actual = checker.getPermissions(roleKey);
+    const permList = actual.size > 0 ? Array.from(actual).sort().join(", ") : "(none)";
+    throw new Error(
+      `Expected role "${roleKey}" to have permission "${permission}", but it does not. Actual permissions: [${permList}]`
+    );
+  }
+}
+function expectNoPermission(rbac, roleKey, permission) {
+  const checker = toChecker(rbac);
+  if (checker.hasPermission(roleKey, permission)) {
+    throw new Error(
+      `Expected role "${roleKey}" NOT to have permission "${permission}", but it does.`
+    );
+  }
+}
+function expectRolePermissions(rbac, roleKey, expected) {
+  const checker = toChecker(rbac);
+  const actual = checker.getPermissions(roleKey);
+  const expectedSet = new Set(expected);
+  const missing = [];
+  const extra = [];
+  for (const perm of expectedSet) {
+    if (!actual.has(perm)) {
+      missing.push(perm);
+    }
+  }
+  for (const perm of actual) {
+    if (!expectedSet.has(perm)) {
+      extra.push(perm);
+    }
+  }
+  if (missing.length > 0 || extra.length > 0) {
+    const parts = [];
+    if (missing.length > 0) {
+      parts.push(`Missing: [${missing.sort().join(", ")}]`);
+    }
+    if (extra.length > 0) {
+      parts.push(`Extra: [${extra.sort().join(", ")}]`);
+    }
+    throw new Error(
+      `Role "${roleKey}" permissions do not match expected set. ${parts.join(". ")}`
+    );
+  }
+}
+export {
+  RbacChecker,
+  createTestRbacConfig,
+  createTestResource,
+  createTestRole,
+  expectNoPermission,
+  expectPermission,
+  expectRolePermissions
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@auth-gate/testing",
-  "version": "0.9.3",
+  "version": "0.11.0",
   "type": "module",
   "exports": {
     ".": {
@@ -17,20 +17,33 @@
       "types": "./dist/cypress.d.ts",
       "import": "./dist/cypress.mjs",
       "require": "./dist/cypress.cjs"
+    },
+    "./billing": {
+      "types": "./dist/billing/index.d.ts",
+      "import": "./dist/billing/index.mjs",
+      "require": "./dist/billing/index.cjs"
+    },
+    "./rbac": {
+      "types": "./dist/rbac/index.d.ts",
+      "import": "./dist/rbac/index.mjs",
+      "require": "./dist/rbac/index.cjs"
     }
   },
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "icon.png"
   ],
   "dependencies": {
-    "@auth-gate/core": "0.9.3"
+    "@auth-gate/core": "0.11.0"
   },
   "peerDependencies": {
     "@playwright/test": ">=1.40",
-    "cypress": ">=12"
+    "cypress": ">=12",
+    "@auth-gate/billing": ">=0.1.0",
+    "@auth-gate/rbac": ">=0.1.0"
   },
   "peerDependenciesMeta": {
     "@playwright/test": {
@@ -38,16 +51,26 @@
     },
     "cypress": {
       "optional": true
+    },
+    "@auth-gate/billing": {
+      "optional": true
+    },
+    "@auth-gate/rbac": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@playwright/test": "^1.50.0",
     "cypress": "^13.0.0",
     "tsup": "^8.0.0",
-    "typescript": "^5"
+    "typescript": "^5",
+    "vitest": "^3.0.0",
+    "@auth-gate/billing": "0.11.0",
+    "@auth-gate/rbac": "0.11.0"
   },
   "scripts": {
     "build": "tsup",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
   }
 }