@zap-studio/permit 0.3.3 → 1.0.0

package/dist/conditions.js

@@ -0,0 +1,180 @@
+//#region src/conditions.ts
+/**
+* Returns a policy function that always allows the action.
+*
+* @example
+* ```ts
+* const policy = createPolicy({
+*   resources,
+*   actions,
+*   rules: {
+*     post: {
+*       read: allow(), // Always allow reading posts
+*     },
+*   },
+* });
+* ```
+*/
+const allow = () => () => "allow";
+/**
+* Returns a policy function that always denies the action.
+*
+* @example
+* ```ts
+* const policy = createPolicy({
+*   resources,
+*   actions,
+*   rules: {
+*     post: {
+*       delete: deny(), // Never allow deleting posts
+*     },
+*   },
+* });
+* ```
+*/
+const deny = () => () => "deny";
+/**
+* Returns a policy function that allows or denies based on a condition.
+*
+* @example
+* ```ts
+* const policy = createPolicy({
+*   resources,
+*   actions,
+*   rules: {
+*     post: {
+*       write: when((ctx, action, resource) => ctx.user.id === resource.authorId),
+*     },
+*   },
+* });
+* ```
+*/
+const when = (condition) => (context, action, resource) => condition(context, action, resource) ? "allow" : "deny";
+/**
+* Returns a condition function that returns `true` if all conditions are met.
+*
+* @example
+* ```ts
+* const isOwnerAndPublished = and(
+*   (ctx, action, resource) => ctx.user.id === resource.authorId,
+*   (ctx, action, resource) => resource.status === "published"
+* );
+*
+* rules: {
+*   post: {
+*     delete: when(isOwnerAndPublished),
+*   },
+* }
+* ```
+*/
+const and = (...conditions) => (context, action, resource) => conditions.every((condition) => condition(context, action, resource));
+/**
+* Returns a condition function that returns `true` if any condition is met.
+*
+* @example
+* ```ts
+* const isOwnerOrAdmin = or(
+*   (ctx, action, resource) => ctx.user.id === resource.authorId,
+*   (ctx, action, resource) => ctx.user.role === "admin"
+* );
+*
+* rules: {
+*   post: {
+*     write: when(isOwnerOrAdmin),
+*   },
+* }
+* ```
+*/
+const or = (...conditions) => (context, action, resource) => conditions.some((condition) => condition(context, action, resource));
+/**
+* Returns a condition function that negates another condition.
+*
+* @example
+* ```ts
+* const isNotOwner = not((ctx, action, resource) => ctx.user.id === resource.authorId);
+*
+* rules: {
+*   post: {
+*     like: when(isNotOwner), // Can only like posts you don't own
+*   },
+* }
+* ```
+*/
+const not = (condition) => (context, action, resource) => !condition(context, action, resource);
+/**
+* Returns a condition function that checks if a context property equals a value.
+*
+* @example
+* ```ts
+* rules: {
+*   post: {
+*     write: when(has("role", "admin")), // Only admins can write
+*   },
+* }
+* ```
+*/
+const has = (key, value) => (context) => context[key] === value;
+/**
+* Collects all roles including inherited ones from a role hierarchy.
+*
+* @example
+* ```ts
+* type Role = "guest" | "user" | "admin";
+*
+* const hierarchy: RoleHierarchy<Role> = {
+*   guest: [],
+*   user: ["guest"],
+*   admin: ["user"],
+* };
+*
+* collectInheritedRoles(["admin"], hierarchy);
+* // Returns: Set { "admin", "user", "guest" }
+* ```
+*/
+const collectInheritedRoles = (roles, hierarchy) => {
+	const inherited = /* @__PURE__ */ new Set();
+	const add = (role) => {
+		if (inherited.has(role)) return;
+		inherited.add(role);
+		const baseRoles = hierarchy[role] ?? [];
+		for (const baseRole of baseRoles) add(baseRole);
+	};
+	for (const role of roles) add(role);
+	return inherited;
+};
+/**
+* Returns a condition function that checks if the user has a specific role.
+* Supports role hierarchy for inherited permissions.
+*
+* @example
+* ```ts
+* // Without hierarchy
+* rules: {
+*   post: {
+*     delete: when(hasRole("admin")),
+*   },
+* }
+*
+* // With hierarchy
+* const hierarchy = {
+*   guest: [],
+*   user: ["guest"],
+*   admin: ["user"],
+* };
+*
+* rules: {
+*   post: {
+*     read: when(hasRole("guest", hierarchy)), // Admins and users can also read
+*   },
+* }
+* ```
+*/
+const hasRole = (role, hierarchy) => (context) => {
+	const userRoles = Array.isArray(context.role) ? context.role : [context.role];
+	if (hierarchy === void 0) return userRoles.includes(role);
+	return collectInheritedRoles(userRoles, hierarchy).has(role);
+};
+//#endregion
+export { allow, and, collectInheritedRoles, deny, has, hasRole, not, or, when };
+
+//# sourceMappingURL=conditions.js.map

package/dist/conditions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conditions.js","names":[],"sources":["../src/conditions.ts"],"sourcesContent":["/**\n * Policy and condition combinators: `allow`, `deny`, `when`, boolean\n * composition, and role helpers.\n *\n * @module @zap-studio/permit/conditions\n */\n\nimport type {\n  ConditionFn,\n  Context,\n  HasRoleFn,\n  PolicyFn,\n  Role,\n  RoleHierarchy,\n} from \"./types.js\";\n\n/**\n * Returns a policy function that always allows the action.\n *\n * @example\n * ```ts\n * const policy = createPolicy({\n *   resources,\n *   actions,\n *   rules: {\n *     post: {\n *       read: allow(), // Always allow reading posts\n *     },\n *   },\n * });\n * ```\n */\nexport const allow =\n  <\n    TContext extends Context,\n    TAction extends string = string,\n    TResource = unknown,\n  >(): PolicyFn<TContext, TAction, TResource> =>\n  () =>\n    \"allow\";\n\n/**\n * Returns a policy function that always denies the action.\n *\n * @example\n * ```ts\n * const policy = createPolicy({\n *   resources,\n *   actions,\n *   rules: {\n *     post: {\n *       delete: deny(), // Never allow deleting posts\n *     },\n *   },\n * });\n * ```\n */\nexport const deny =\n  <\n    TContext extends Context,\n    TAction extends string = string,\n    TResource = unknown,\n  >(): PolicyFn<TContext, TAction, TResource> =>\n  () =>\n    \"deny\";\n\n/**\n * Returns a policy function that allows or denies based on a condition.\n *\n * @example\n * ```ts\n * const policy = createPolicy({\n *   resources,\n *   actions,\n *   rules: {\n *     post: {\n *       write: when((ctx, action, resource) => ctx.user.id === resource.authorId),\n *     },\n *   },\n * });\n * ```\n */\nexport const when =\n  <\n    TContext extends Context,\n    TAction extends string = string,\n    TResource = unknown,\n  >(\n    condition: ConditionFn<TContext, TAction, TResource>\n  ): PolicyFn<TContext, TAction, TResource> =>\n  (context, action, resource) =>\n    condition(context, action, resource) ? \"allow\" : \"deny\";\n\n/**\n * Returns a condition function that returns `true` if all conditions are met.\n *\n * @example\n * ```ts\n * const isOwnerAndPublished = and(\n *   (ctx, action, resource) => ctx.user.id === resource.authorId,\n *   (ctx, action, resource) => resource.status === \"published\"\n * );\n *\n * rules: {\n *   post: {\n *     delete: when(isOwnerAndPublished),\n *   },\n * }\n * ```\n */\nexport const and =\n  <\n    TContext extends Context,\n    TAction extends string = string,\n    TResource = unknown,\n  >(\n    ...conditions: ConditionFn<TContext, TAction, TResource>[]\n  ): ConditionFn<TContext, TAction, TResource> =>\n  (context, action, resource) =>\n    conditions.every((condition) => condition(context, action, resource));\n\n/**\n * Returns a condition function that returns `true` if any condition is met.\n *\n * @example\n * ```ts\n * const isOwnerOrAdmin = or(\n *   (ctx, action, resource) => ctx.user.id === resource.authorId,\n *   (ctx, action, resource) => ctx.user.role === \"admin\"\n * );\n *\n * rules: {\n *   post: {\n *     write: when(isOwnerOrAdmin),\n *   },\n * }\n * ```\n */\nexport const or =\n  <\n    TContext extends Context,\n    TAction extends string = string,\n    TResource = unknown,\n  >(\n    ...conditions: ConditionFn<TContext, TAction, TResource>[]\n  ): ConditionFn<TContext, TAction, TResource> =>\n  (context, action, resource) =>\n    conditions.some((condition) => condition(context, action, resource));\n\n/**\n * Returns a condition function that negates another condition.\n *\n * @example\n * ```ts\n * const isNotOwner = not((ctx, action, resource) => ctx.user.id === resource.authorId);\n *\n * rules: {\n *   post: {\n *     like: when(isNotOwner), // Can only like posts you don't own\n *   },\n * }\n * ```\n */\nexport const not =\n  <\n    TContext extends Context,\n    TAction extends string = string,\n    TResource = unknown,\n  >(\n    condition: ConditionFn<TContext, TAction, TResource>\n  ): ConditionFn<TContext, TAction, TResource> =>\n  (context, action, resource) =>\n    !condition(context, action, resource);\n\n/**\n * Returns a condition function that checks if a context property equals a value.\n *\n * @example\n * ```ts\n * rules: {\n *   post: {\n *     write: when(has(\"role\", \"admin\")), // Only admins can write\n *   },\n * }\n * ```\n */\nexport const has =\n  <TContext extends Context, K extends keyof TContext>(\n    key: K,\n    value: TContext[K]\n  ): ConditionFn<TContext> =>\n  (context) =>\n    context[key] === value;\n\n/**\n * Collects all roles including inherited ones from a role hierarchy.\n *\n * @example\n * ```ts\n * type Role = \"guest\" | \"user\" | \"admin\";\n *\n * const hierarchy: RoleHierarchy<Role> = {\n *   guest: [],\n *   user: [\"guest\"],\n *   admin: [\"user\"],\n * };\n *\n * collectInheritedRoles([\"admin\"], hierarchy);\n * // Returns: Set { \"admin\", \"user\", \"guest\" }\n * ```\n */\nexport const collectInheritedRoles = <TRole extends Role = Role>(\n  roles: TRole[],\n  hierarchy: RoleHierarchy<TRole>\n): Set<TRole> => {\n  const inherited = new Set<TRole>();\n\n  const add = (role: TRole): void => {\n    if (inherited.has(role)) {\n      return;\n    }\n\n    inherited.add(role);\n    const baseRoles = hierarchy[role] ?? [];\n    for (const baseRole of baseRoles) {\n      add(baseRole);\n    }\n  };\n\n  for (const role of roles) {\n    add(role);\n  }\n  return inherited;\n};\n\n/**\n * Returns a condition function that checks if the user has a specific role.\n * Supports role hierarchy for inherited permissions.\n *\n * @example\n * ```ts\n * // Without hierarchy\n * rules: {\n *   post: {\n *     delete: when(hasRole(\"admin\")),\n *   },\n * }\n *\n * // With hierarchy\n * const hierarchy = {\n *   guest: [],\n *   user: [\"guest\"],\n *   admin: [\"user\"],\n * };\n *\n * rules: {\n *   post: {\n *     read: when(hasRole(\"guest\", hierarchy)), // Admins and users can also read\n *   },\n * }\n * ```\n */\nexport const hasRole: HasRoleFn =\n  (\n    role: Role,\n    hierarchy?: RoleHierarchy\n  ): ConditionFn<{ role: Role | Role[] }> =>\n  (context) => {\n    const userRoles = Array.isArray(context.role)\n      ? context.role\n      : [context.role];\n\n    if (hierarchy === undefined) {\n      return userRoles.includes(role);\n    }\n\n    const inherited = collectInheritedRoles(userRoles, hierarchy);\n    return inherited.has(role);\n  };\n"],"mappings":";;;;;;;;;;;;;;;;;AAgCA,MAAa,oBAOT;;;;;;;;;;;;;;;;;AAkBJ,MAAa,mBAOT;;;;;;;;;;;;;;;;;AAkBJ,MAAa,QAMT,eAED,SAAS,QAAQ,aAChB,UAAU,SAAS,QAAQ,QAAQ,IAAI,UAAU;;;;;;;;;;;;;;;;;;AAmBrD,MAAa,OAMT,GAAG,gBAEJ,SAAS,QAAQ,aAChB,WAAW,OAAO,cAAc,UAAU,SAAS,QAAQ,QAAQ,CAAC;;;;;;;;;;;;;;;;;;AAmBxE,MAAa,MAMT,GAAG,gBAEJ,SAAS,QAAQ,aAChB,WAAW,MAAM,cAAc,UAAU,SAAS,QAAQ,QAAQ,CAAC;;;;;;;;;;;;;;;AAgBvE,MAAa,OAMT,eAED,SAAS,QAAQ,aAChB,CAAC,UAAU,SAAS,QAAQ,QAAQ;;;;;;;;;;;;;AAcxC,MAAa,OAET,KACA,WAED,YACC,QAAQ,SAAS;;;;;;;;;;;;;;;;;;AAmBrB,MAAa,yBACX,OACA,cACe;CACf,MAAM,4BAAY,IAAI,IAAW;CAEjC,MAAM,OAAO,SAAsB;EACjC,IAAI,UAAU,IAAI,IAAI,GACpB;EAGF,UAAU,IAAI,IAAI;EAClB,MAAM,YAAY,UAAU,SAAS,CAAC;EACtC,KAAK,MAAM,YAAY,WACrB,IAAI,QAAQ;CAEhB;CAEA,KAAK,MAAM,QAAQ,OACjB,IAAI,IAAI;CAEV,OAAO;AACT;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,MAAa,WAET,MACA,eAED,YAAY;CACX,MAAM,YAAY,MAAM,QAAQ,QAAQ,IAAI,IACxC,QAAQ,OACR,CAAC,QAAQ,IAAI;CAEjB,IAAI,cAAc,KAAA,GAChB,OAAO,UAAU,SAAS,IAAI;CAIhC,OADkB,sBAAsB,WAAW,SACpC,CAAC,CAAC,IAAI,IAAI;AAC3B"}

package/dist/{errors.d.mts → errors.d.ts}

@@ -7,6 +7,20 @@
 /**
  * Represents an error that occurs during policy evaluation or enforcement.
  * Use this error to indicate issues related to policy logic, configuration, or execution.
+ *
+ * @example
+ * ```ts
+ * import { PolicyError } from "@zap-studio/permit";
+ *
+ * try {
+ *   const policy = createPolicy(config);
+ *   await policy.can(ctx, "post:read", post);
+ * } catch (error) {
+ *   if (error instanceof PolicyError) {
+ *     console.error("Invalid policy configuration:", error.message);
+ *   }
+ * }
+ * ```
  */
 declare class PolicyError extends Error {
   /**
@@ -18,4 +32,4 @@ declare class PolicyError extends Error {
 }
 //#endregion
 export { PolicyError };
-//# sourceMappingURL=errors.d.mts.map
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","names":[],"sources":["../src/errors.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;cAwBa,oBAAoB;;;;;;EAM/B,YAAY"}

package/dist/{errors.mjs → errors.js}

@@ -7,6 +7,20 @@
 /**
 * Represents an error that occurs during policy evaluation or enforcement.
 * Use this error to indicate issues related to policy logic, configuration, or execution.
+*
+* @example
+* ```ts
+* import { PolicyError } from "@zap-studio/permit";
+*
+* try {
+*   const policy = createPolicy(config);
+*   await policy.can(ctx, "post:read", post);
+* } catch (error) {
+*   if (error instanceof PolicyError) {
+*     console.error("Invalid policy configuration:", error.message);
+*   }
+* }
+* ```
 */
 var PolicyError = class extends Error {
 	/**
@@ -22,4 +36,4 @@ var PolicyError = class extends Error {
 //#endregion
 export { PolicyError };
 
-//# sourceMappingURL=errors.mjs.map
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","names":[],"sources":["../src/errors.ts"],"sourcesContent":["/**\n * Error primitives for policy evaluation and configuration failures.\n *\n * @module @zap-studio/permit/errors\n */\n\n/**\n * Represents an error that occurs during policy evaluation or enforcement.\n * Use this error to indicate issues related to policy logic, configuration, or execution.\n *\n * @example\n * ```ts\n * import { PolicyError } from \"@zap-studio/permit\";\n *\n * try {\n *   const policy = createPolicy(config);\n *   await policy.can(ctx, \"post:read\", post);\n * } catch (error) {\n *   if (error instanceof PolicyError) {\n *     console.error(\"Invalid policy configuration:\", error.message);\n *   }\n * }\n * ```\n */\nexport class PolicyError extends Error {\n  /**\n   * Creates a policy error with a human-readable message.\n   *\n   * @param message - Error message describing the policy failure.\n   */\n  constructor(message: string) {\n    super(message);\n    this.name = \"PolicyError\";\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAwBA,IAAa,cAAb,cAAiC,MAAM;;;;;;CAMrC,YAAY,SAAiB;EAC3B,MAAM,OAAO;EACb,KAAK,OAAO;CACd;AACF"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import { ActionPolicyMap, Actions, ConditionFn, Context, Decision, InferAction, InferPermission, InferResource, PermitConfig, Policy, PolicyFn, Resources, Role, RoleHierarchy, Rules } from "./types.js";
+import { allow, and, collectInheritedRoles, deny, has, hasRole, not, or, when } from "./conditions.js";
+import { PolicyError } from "./errors.js";
+import { createPolicy, mergePoliciesAnd, mergePoliciesOr } from "./policy.js";
+export { type ActionPolicyMap, type Actions, type ConditionFn, type Context, type Decision, type InferAction, type InferPermission, type InferResource, type PermitConfig, type Policy, PolicyError, type PolicyFn, type Resources, type Role, type RoleHierarchy, type Rules, allow, and, collectInheritedRoles, createPolicy, deny, has, hasRole, mergePoliciesAnd, mergePoliciesOr, not, or, when };

package/dist/index.js

@@ -0,0 +1,4 @@
+import { allow, and, collectInheritedRoles, deny, has, hasRole, not, or, when } from "./conditions.js";
+import { PolicyError } from "./errors.js";
+import { createPolicy, mergePoliciesAnd, mergePoliciesOr } from "./policy.js";
+export { PolicyError, allow, and, collectInheritedRoles, createPolicy, deny, has, hasRole, mergePoliciesAnd, mergePoliciesOr, not, or, when };

package/dist/policy.d.ts

@@ -0,0 +1,91 @@
+import { Actions, Context, PermitConfig, Policy, Resources } from "./types.js";
+//#region src/policy.d.ts
+/**
+ * Creates a type-safe policy from resource schemas, actions, and rules.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import { createPolicy, allow, deny, when } from "@zap-studio/permit";
+ * import type { Resources, Actions } from "@zap-studio/permit/types";
+ *
+ * // Define resource schemas
+ * const resources = {
+ *   post: z.object({
+ *     id: z.string(),
+ *     authorId: z.string(),
+ *     visibility: z.enum(["public", "private"]),
+ *   }),
+ *   comment: z.object({
+ *     id: z.string(),
+ *     postId: z.string(),
+ *     authorId: z.string(),
+ *   }),
+ * } satisfies Resources;
+ *
+ * // Define actions per resource
+ * const actions = {
+ *   post: ["read", "write", "delete"],
+ *   comment: ["read", "write"],
+ * } as const satisfies Actions<typeof resources>;
+ *
+ * // Define context type
+ * type AppContext = { user: { id: string; role: string } };
+ *
+ * // Create the policy
+ * const policy = createPolicy<AppContext>({
+ *   resources,
+ *   actions,
+ *   rules: {
+ *     post: {
+ *       read: when((ctx, action, resource) => resource.visibility === "public"),
+ *       write: when((ctx, action, resource) => ctx.user.id === resource.authorId),
+ *       delete: deny(),
+ *     },
+ *     comment: {
+ *       read: allow(),
+ *       write: when((ctx, action, resource) => ctx.user.id === resource.authorId),
+ *     },
+ *   },
+ * });
+ *
+ * // Check permissions
+ * const post = { id: "1", authorId: "user-1", visibility: "public" as const };
+ * await policy.can(ctx, "post:read", post); // true
+ * await policy.can(ctx, "post:write", post); // depends on ctx.user.id
+ * ```
+ */
+declare const createPolicy: <TContext extends Context, TResources extends Resources = Resources, TActions extends Actions<TResources> = Actions<TResources>>(config: PermitConfig<TContext, TResources, TActions>) => Policy<TContext, TResources, TActions>;
+/**
+ * Merges multiple policies into one, requiring every policy to allow.
+ * If any policy denies, the merged policy denies. Policies are evaluated
+ * in parallel; every policy is invoked regardless of outcome.
+ *
+ * @example
+ * ```ts
+ * const basePolicy = createPolicy({ ... });
+ * const adminPolicy = createPolicy({ ... });
+ *
+ * const merged = mergePoliciesAnd(basePolicy, adminPolicy);
+ * // Both policies must allow for the action to be permitted
+ * ```
+ */
+declare const mergePoliciesAnd: <TContext extends Context, TResources extends Resources = Resources, TActions extends Actions<TResources> = Actions<TResources>>(...policies: Policy<TContext, TResources, TActions>[]) => Policy<TContext, TResources, TActions>;
+/**
+ * Merges multiple policies into one, requiring at least one policy to allow.
+ * If every policy denies, the merged policy denies. Policies are evaluated
+ * in parallel; every policy is invoked regardless of outcome.
+ *
+ * @example
+ * ```ts
+ * const guestPolicy = createPolicy({ ... });
+ * const memberPolicy = createPolicy({ ... });
+ *
+ * const merged = mergePoliciesOr(guestPolicy, memberPolicy);
+ * // If either policy allows, the action is permitted
+ * ```
+ */
+declare const mergePoliciesOr: <TContext extends Context, TResources extends Resources = Resources, TActions extends Actions<TResources> = Actions<TResources>>(...policies: Policy<TContext, TResources, TActions>[]) => Policy<TContext, TResources, TActions>;
+//#endregion
+export { createPolicy, mergePoliciesAnd, mergePoliciesOr };
+//# sourceMappingURL=policy.d.ts.map

package/dist/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","names":[],"sources":["../src/policy.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA8Ga,eACX,iBAAiB,SACjB,mBAAmB,YAAY,WAC/B,iBAAiB,QAAQ,cAAc,QAAQ,aAE/C,QAAQ,aAAa,UAAU,YAAY,cAC1C,OAAO,UAAU,YAAY;;;;;;;;;;;;;;;cAgJnB,mBACX,iBAAiB,SACjB,mBAAmB,YAAY,WAC/B,iBAAiB,QAAQ,cAAc,QAAQ,gBAE5C,UAAU,OAAO,UAAU,YAAY,gBACzC,OAAO,UAAU,YAAY;;;;;;;;;;;;;;;cAiBnB,kBACX,iBAAiB,SACjB,mBAAmB,YAAY,WAC/B,iBAAiB,QAAQ,cAAc,QAAQ,gBAE5C,UAAU,OAAO,UAAU,YAAY,gBACzC,OAAO,UAAU,YAAY"}

package/dist/policy.js

@@ -0,0 +1,156 @@
+import { PolicyError } from "./errors.js";
+import { createStandardValidator } from "@zap-studio/validation";
+//#region src/policy.ts
+/**
+* Splits a typed `resource:action` permission string into its parts.
+* Returns `null` when the string is malformed (missing/empty part or extra
+* segments) or `resourceType` is not one of `actions`' keys.
+*/
+const parsePermission = (permission, actions) => {
+	const isValidResourceKey = (value) => Object.keys(actions).includes(value);
+	const [resourceTypeValue, actionValue, ...rest] = permission.split(":");
+	if (resourceTypeValue === void 0 || resourceTypeValue.length === 0 || actionValue === void 0 || actionValue.length === 0 || rest.length > 0 || !isValidResourceKey(resourceTypeValue)) return null;
+	return {
+		action: actionValue,
+		resourceType: resourceTypeValue
+	};
+};
+/**
+* Creates a type-safe policy from resource schemas, actions, and rules.
+*
+* @example
+* ```ts
+* import { z } from "zod";
+* import { createPolicy, allow, deny, when } from "@zap-studio/permit";
+* import type { Resources, Actions } from "@zap-studio/permit/types";
+*
+* // Define resource schemas
+* const resources = {
+*   post: z.object({
+*     id: z.string(),
+*     authorId: z.string(),
+*     visibility: z.enum(["public", "private"]),
+*   }),
+*   comment: z.object({
+*     id: z.string(),
+*     postId: z.string(),
+*     authorId: z.string(),
+*   }),
+* } satisfies Resources;
+*
+* // Define actions per resource
+* const actions = {
+*   post: ["read", "write", "delete"],
+*   comment: ["read", "write"],
+* } as const satisfies Actions<typeof resources>;
+*
+* // Define context type
+* type AppContext = { user: { id: string; role: string } };
+*
+* // Create the policy
+* const policy = createPolicy<AppContext>({
+*   resources,
+*   actions,
+*   rules: {
+*     post: {
+*       read: when((ctx, action, resource) => resource.visibility === "public"),
+*       write: when((ctx, action, resource) => ctx.user.id === resource.authorId),
+*       delete: deny(),
+*     },
+*     comment: {
+*       read: allow(),
+*       write: when((ctx, action, resource) => ctx.user.id === resource.authorId),
+*     },
+*   },
+* });
+*
+* // Check permissions
+* const post = { id: "1", authorId: "user-1", visibility: "public" as const };
+* await policy.can(ctx, "post:read", post); // true
+* await policy.can(ctx, "post:write", post); // depends on ctx.user.id
+* ```
+*/
+const createPolicy = (config) => {
+	const { rules, resources, actions } = config;
+	const validators = /* @__PURE__ */ new Map();
+	const getValidatedResource = async (resourceType, resource) => {
+		const validator = validators.get(resourceType);
+		if (validator === void 0) return null;
+		try {
+			const result = await validator(resource);
+			if (result.issues) return null;
+			return result.value;
+		} catch (error) {
+			console.warn(`Resource validation failed for ${String(resourceType)}: ${String(error)}`);
+			return null;
+		}
+	};
+	const hasAllowedAction = (resourceType, action) => actions[resourceType]?.includes(action) ?? false;
+	const evaluatePolicy = (context, resourceType, action, resource) => {
+		const policyFn = rules[resourceType]?.[action];
+		if (policyFn === void 0) return false;
+		try {
+			return policyFn(context, action, resource) === "allow";
+		} catch (error) {
+			console.warn(`Policy evaluation error for ${String(resourceType)}.${action}: ${String(error)}`);
+			return false;
+		}
+	};
+	for (const key of Object.keys(resources)) {
+		const schema = resources[key];
+		if (schema === void 0) throw new PolicyError(`Missing schema for resource: ${String(key)}`);
+		const validator = createStandardValidator(schema);
+		validators.set(key, async (input) => await validator(input));
+	}
+	return { async can(context, permission, resource) {
+		const parsedPermission = parsePermission(permission, actions);
+		if (parsedPermission === null) return false;
+		const { action, resourceType } = parsedPermission;
+		if (!hasAllowedAction(resourceType, action)) return false;
+		const validatedResource = await getValidatedResource(resourceType, resource);
+		if (validatedResource === null) return false;
+		return evaluatePolicy(context, resourceType, action, validatedResource);
+	} };
+};
+const mergePoliciesWithStrategy = (policies, strategy) => ({ async can(context, permission, resource) {
+	if (policies.length === 0) return false;
+	const results = (await Promise.allSettled(policies.map(async (policy) => await policy.can(context, permission, resource)))).map((result) => {
+		if (result.status === "fulfilled") return result.value;
+		return false;
+	});
+	return strategy === "and" ? results.every(Boolean) : results.some(Boolean);
+} });
+/**
+* Merges multiple policies into one, requiring every policy to allow.
+* If any policy denies, the merged policy denies. Policies are evaluated
+* in parallel; every policy is invoked regardless of outcome.
+*
+* @example
+* ```ts
+* const basePolicy = createPolicy({ ... });
+* const adminPolicy = createPolicy({ ... });
+*
+* const merged = mergePoliciesAnd(basePolicy, adminPolicy);
+* // Both policies must allow for the action to be permitted
+* ```
+*/
+const mergePoliciesAnd = (...policies) => mergePoliciesWithStrategy(policies, "and");
+/**
+* Merges multiple policies into one, requiring at least one policy to allow.
+* If every policy denies, the merged policy denies. Policies are evaluated
+* in parallel; every policy is invoked regardless of outcome.
+*
+* @example
+* ```ts
+* const guestPolicy = createPolicy({ ... });
+* const memberPolicy = createPolicy({ ... });
+*
+* const merged = mergePoliciesOr(guestPolicy, memberPolicy);
+* // If either policy allows, the action is permitted
+* ```
+*/
+const mergePoliciesOr = (...policies) => mergePoliciesWithStrategy(policies, "or");
+//#endregion
+export { createPolicy, mergePoliciesAnd, mergePoliciesOr };
+
+//# sourceMappingURL=policy.js.map

package/dist/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","names":[],"sources":["../src/policy.ts"],"sourcesContent":["/**\n * Policy creation and composition: `createPolicy`, `mergePoliciesAnd`, and\n * `mergePoliciesOr`.\n *\n * @module @zap-studio/permit/policy\n */\n\nimport type { StandardSchemaV1 } from \"@zap-studio/validation\";\nimport { createStandardValidator } from \"@zap-studio/validation\";\n\nimport { PolicyError } from \"./errors.js\";\nimport type {\n  Actions,\n  Context,\n  InferAction,\n  InferResource,\n  PermitConfig,\n  Policy,\n  Resources,\n} from \"./types.js\";\n\n/**\n * Splits a typed `resource:action` permission string into its parts.\n * Returns `null` when the string is malformed (missing/empty part or extra\n * segments) or `resourceType` is not one of `actions`' keys.\n */\nconst parsePermission = <\n  TResources extends Resources,\n  TActions extends Actions<TResources>,\n  K extends keyof TResources & keyof TActions,\n>(\n  permission: `${K & string}:${InferAction<TResources, TActions, K> & string}`,\n  actions: TActions\n): { action: InferAction<TResources, TActions, K>; resourceType: K } | null => {\n  const isValidResourceKey = (value: string): value is K & string =>\n    Object.keys(actions).includes(value);\n\n  const [resourceTypeValue, actionValue, ...rest] = permission.split(\":\");\n  if (\n    resourceTypeValue === undefined ||\n    resourceTypeValue.length === 0 ||\n    actionValue === undefined ||\n    actionValue.length === 0 ||\n    rest.length > 0 ||\n    !isValidResourceKey(resourceTypeValue)\n  ) {\n    return null;\n  }\n\n  return {\n    action: actionValue,\n    resourceType: resourceTypeValue,\n  };\n};\n\n/**\n * Creates a type-safe policy from resource schemas, actions, and rules.\n *\n * @example\n * ```ts\n * import { z } from \"zod\";\n * import { createPolicy, allow, deny, when } from \"@zap-studio/permit\";\n * import type { Resources, Actions } from \"@zap-studio/permit/types\";\n *\n * // Define resource schemas\n * const resources = {\n *   post: z.object({\n *     id: z.string(),\n *     authorId: z.string(),\n *     visibility: z.enum([\"public\", \"private\"]),\n *   }),\n *   comment: z.object({\n *     id: z.string(),\n *     postId: z.string(),\n *     authorId: z.string(),\n *   }),\n * } satisfies Resources;\n *\n * // Define actions per resource\n * const actions = {\n *   post: [\"read\", \"write\", \"delete\"],\n *   comment: [\"read\", \"write\"],\n * } as const satisfies Actions<typeof resources>;\n *\n * // Define context type\n * type AppContext = { user: { id: string; role: string } };\n *\n * // Create the policy\n * const policy = createPolicy<AppContext>({\n *   resources,\n *   actions,\n *   rules: {\n *     post: {\n *       read: when((ctx, action, resource) => resource.visibility === \"public\"),\n *       write: when((ctx, action, resource) => ctx.user.id === resource.authorId),\n *       delete: deny(),\n *     },\n *     comment: {\n *       read: allow(),\n *       write: when((ctx, action, resource) => ctx.user.id === resource.authorId),\n *     },\n *   },\n * });\n *\n * // Check permissions\n * const post = { id: \"1\", authorId: \"user-1\", visibility: \"public\" as const };\n * await policy.can(ctx, \"post:read\", post); // true\n * await policy.can(ctx, \"post:write\", post); // depends on ctx.user.id\n * ```\n */\nexport const createPolicy = <\n  TContext extends Context,\n  TResources extends Resources = Resources,\n  TActions extends Actions<TResources> = Actions<TResources>,\n>(\n  config: PermitConfig<TContext, TResources, TActions>\n): Policy<TContext, TResources, TActions> => {\n  const { rules, resources, actions } = config;\n  const validators = new Map<\n    keyof TResources,\n    (input: unknown) => Promise<StandardSchemaV1.Result<unknown>>\n  >();\n\n  const getValidatedResource = async <K extends keyof TResources>(\n    resourceType: K,\n    resource: InferResource<TResources, K>\n  ): Promise<InferResource<TResources, K> | null> => {\n    const validator = validators.get(resourceType);\n    if (validator === undefined) {\n      return null;\n    }\n    try {\n      const result = await validator(resource);\n      if (result.issues) {\n        return null;\n      }\n      return result.value;\n    } catch (error) {\n      console.warn(\n        `Resource validation failed for ${String(resourceType)}: ${String(error)}`\n      );\n      return null;\n    }\n  };\n\n  const hasAllowedAction = <K extends keyof TResources & keyof TActions>(\n    resourceType: K,\n    action: InferAction<TResources, TActions, K>\n  ): boolean => actions[resourceType]?.includes(action) ?? false;\n\n  const evaluatePolicy = <K extends keyof TResources & keyof TActions>(\n    context: TContext,\n    resourceType: K,\n    action: InferAction<TResources, TActions, K>,\n    resource: InferResource<TResources, K>\n  ): boolean => {\n    const policyFn = rules[resourceType]?.[action];\n    if (policyFn === undefined) {\n      return false;\n    }\n\n    try {\n      return policyFn(context, action, resource) === \"allow\";\n    } catch (error) {\n      console.warn(\n        `Policy evaluation error for ${String(resourceType)}.${action}: ${String(error)}`\n      );\n      return false;\n    }\n  };\n\n  for (const key of Object.keys(resources) as (keyof TResources)[]) {\n    const schema = resources[key];\n    if (schema === undefined) {\n      throw new PolicyError(`Missing schema for resource: ${String(key)}`);\n    }\n    const validator = createStandardValidator(schema);\n    validators.set(key, async (input: unknown) => await validator(input));\n  }\n\n  return {\n    async can<K extends keyof TResources & keyof TActions>(\n      context: TContext,\n      permission: `${K & string}:${InferAction<TResources, TActions, K> & string}`,\n      resource: InferResource<TResources, K>\n    ): Promise<boolean> {\n      const parsedPermission = parsePermission<TResources, TActions, K>(\n        permission,\n        actions\n      );\n      if (parsedPermission === null) {\n        return false;\n      }\n\n      const { action, resourceType } = parsedPermission;\n      if (!hasAllowedAction(resourceType, action)) {\n        return false;\n      }\n\n      const validatedResource = await getValidatedResource(\n        resourceType,\n        resource\n      );\n      if (validatedResource === null) {\n        return false;\n      }\n\n      return evaluatePolicy(context, resourceType, action, validatedResource);\n    },\n  };\n};\n\nconst mergePoliciesWithStrategy = <\n  TContext extends Context,\n  TResources extends Resources = Resources,\n  TActions extends Actions<TResources> = Actions<TResources>,\n>(\n  policies: Policy<TContext, TResources, TActions>[],\n  strategy: \"and\" | \"or\"\n): Policy<TContext, TResources, TActions> => ({\n  async can<K extends keyof TResources & keyof TActions>(\n    context: TContext,\n    permission: `${K & string}:${InferAction<TResources, TActions, K> & string}`,\n    resource: InferResource<TResources, K>\n  ): Promise<boolean> {\n    if (policies.length === 0) {\n      return false;\n    }\n\n    const settled = await Promise.allSettled(\n      policies.map(\n        async (policy) => await policy.can(context, permission, resource)\n      )\n    );\n\n    const results = settled.map((result) => {\n      if (result.status === \"fulfilled\") {\n        return result.value;\n      }\n      return false;\n    });\n\n    return strategy === \"and\" ? results.every(Boolean) : results.some(Boolean);\n  },\n});\n\n/**\n * Merges multiple policies into one, requiring every policy to allow.\n * If any policy denies, the merged policy denies. Policies are evaluated\n * in parallel; every policy is invoked regardless of outcome.\n *\n * @example\n * ```ts\n * const basePolicy = createPolicy({ ... });\n * const adminPolicy = createPolicy({ ... });\n *\n * const merged = mergePoliciesAnd(basePolicy, adminPolicy);\n * // Both policies must allow for the action to be permitted\n * ```\n */\nexport const mergePoliciesAnd = <\n  TContext extends Context,\n  TResources extends Resources = Resources,\n  TActions extends Actions<TResources> = Actions<TResources>,\n>(\n  ...policies: Policy<TContext, TResources, TActions>[]\n): Policy<TContext, TResources, TActions> =>\n  mergePoliciesWithStrategy(policies, \"and\");\n\n/**\n * Merges multiple policies into one, requiring at least one policy to allow.\n * If every policy denies, the merged policy denies. Policies are evaluated\n * in parallel; every policy is invoked regardless of outcome.\n *\n * @example\n * ```ts\n * const guestPolicy = createPolicy({ ... });\n * const memberPolicy = createPolicy({ ... });\n *\n * const merged = mergePoliciesOr(guestPolicy, memberPolicy);\n * // If either policy allows, the action is permitted\n * ```\n */\nexport const mergePoliciesOr = <\n  TContext extends Context,\n  TResources extends Resources = Resources,\n  TActions extends Actions<TResources> = Actions<TResources>,\n>(\n  ...policies: Policy<TContext, TResources, TActions>[]\n): Policy<TContext, TResources, TActions> =>\n  mergePoliciesWithStrategy(policies, \"or\");\n"],"mappings":";;;;;;;;AA0BA,MAAM,mBAKJ,YACA,YAC6E;CAC7E,MAAM,sBAAsB,UAC1B,OAAO,KAAK,OAAO,CAAC,CAAC,SAAS,KAAK;CAErC,MAAM,CAAC,mBAAmB,aAAa,GAAG,QAAQ,WAAW,MAAM,GAAG;CACtE,IACE,sBAAsB,KAAA,KACtB,kBAAkB,WAAW,KAC7B,gBAAgB,KAAA,KAChB,YAAY,WAAW,KACvB,KAAK,SAAS,KACd,CAAC,mBAAmB,iBAAiB,GAErC,OAAO;CAGT,OAAO;EACL,QAAQ;EACR,cAAc;CAChB;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyDA,MAAa,gBAKX,WAC2C;CAC3C,MAAM,EAAE,OAAO,WAAW,YAAY;CACtC,MAAM,6BAAa,IAAI,IAGrB;CAEF,MAAM,uBAAuB,OAC3B,cACA,aACiD;EACjD,MAAM,YAAY,WAAW,IAAI,YAAY;EAC7C,IAAI,cAAc,KAAA,GAChB,OAAO;EAET,IAAI;GACF,MAAM,SAAS,MAAM,UAAU,QAAQ;GACvC,IAAI,OAAO,QACT,OAAO;GAET,OAAO,OAAO;EAChB,SAAS,OAAO;GACd,QAAQ,KACN,kCAAkC,OAAO,YAAY,EAAE,IAAI,OAAO,KAAK,GACzE;GACA,OAAO;EACT;CACF;CAEA,MAAM,oBACJ,cACA,WACY,QAAQ,aAAa,EAAE,SAAS,MAAM,KAAK;CAEzD,MAAM,kBACJ,SACA,cACA,QACA,aACY;EACZ,MAAM,WAAW,MAAM,aAAa,GAAG;EACvC,IAAI,aAAa,KAAA,GACf,OAAO;EAGT,IAAI;GACF,OAAO,SAAS,SAAS,QAAQ,QAAQ,MAAM;EACjD,SAAS,OAAO;GACd,QAAQ,KACN,+BAA+B,OAAO,YAAY,EAAE,GAAG,OAAO,IAAI,OAAO,KAAK,GAChF;GACA,OAAO;EACT;CACF;CAEA,KAAK,MAAM,OAAO,OAAO,KAAK,SAAS,GAA2B;EAChE,MAAM,SAAS,UAAU;EACzB,IAAI,WAAW,KAAA,GACb,MAAM,IAAI,YAAY,gCAAgC,OAAO,GAAG,GAAG;EAErE,MAAM,YAAY,wBAAwB,MAAM;EAChD,WAAW,IAAI,KAAK,OAAO,UAAmB,MAAM,UAAU,KAAK,CAAC;CACtE;CAEA,OAAO,EACL,MAAM,IACJ,SACA,YACA,UACkB;EAClB,MAAM,mBAAmB,gBACvB,YACA,OACF;EACA,IAAI,qBAAqB,MACvB,OAAO;EAGT,MAAM,EAAE,QAAQ,iBAAiB;EACjC,IAAI,CAAC,iBAAiB,cAAc,MAAM,GACxC,OAAO;EAGT,MAAM,oBAAoB,MAAM,qBAC9B,cACA,QACF;EACA,IAAI,sBAAsB,MACxB,OAAO;EAGT,OAAO,eAAe,SAAS,cAAc,QAAQ,iBAAiB;CACxE,EACF;AACF;AAEA,MAAM,6BAKJ,UACA,cAC4C,EAC5C,MAAM,IACJ,SACA,YACA,UACkB;CAClB,IAAI,SAAS,WAAW,GACtB,OAAO;CAST,MAAM,WAAU,MANM,QAAQ,WAC5B,SAAS,IACP,OAAO,WAAW,MAAM,OAAO,IAAI,SAAS,YAAY,QAAQ,CAClE,CACF,EAAA,CAEwB,KAAK,WAAW;EACtC,IAAI,OAAO,WAAW,aACpB,OAAO,OAAO;EAEhB,OAAO;CACT,CAAC;CAED,OAAO,aAAa,QAAQ,QAAQ,MAAM,OAAO,IAAI,QAAQ,KAAK,OAAO;AAC3E,EACF;;;;;;;;;;;;;;;AAgBA,MAAa,oBAKX,GAAG,aAEH,0BAA0B,UAAU,KAAK;;;;;;;;;;;;;;;AAgB3C,MAAa,mBAKX,GAAG,aAEH,0BAA0B,UAAU,IAAI"}