@zap-studio/permit 1.0.0 → 1.1.1

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.1]
+
+### Changed
+
+`@zap-studio/logger` is now an optional peer dependency instead of a regular dependency. Every import from it is type-only (`import type { Logger }`), so it was never pulled in at runtime — pass any object matching the `Logger` shape (including `pino`) with no install required. Existing consumers of `logger?: Logger` are unaffected.
+
+## [1.1.0]
+
+### Added
+
+`createPolicy(...)` gains an optional `logger?: Logger` option (from `@zap-studio/logger`). When provided, it logs allow decisions at `debug` and deny decisions at `info`. Internal-error warnings (resource validation and policy evaluation errors) route through the logger's `warn` instead of `console.warn` when a logger is provided; without one, they still print via `console.warn` as before. See [Logging](https://www.zapstudio.dev/permit/logging).
+
 ## [1.0.0]
 
 ### Changed

package/README.md

@@ -4,6 +4,16 @@ A type-safe, declarative authorization library for TypeScript with [Standard Sch
 
 Full documentation: [zapstudio.dev/permit](https://www.zapstudio.dev/permit)
 
+## Motivation
+
+Authorization checks written by hand, like `if (user.role === "admin")`, spread through a codebase over time. After a while, nobody can answer "who is allowed to delete a post?" without searching the whole app.
+
+A framework like CASL solves the spreading problem, but it comes with its own vocabulary to learn (`subject`, `can`, `cannot`, `rules`), and its rules are not checked against your actual data shapes — you can write a rule that references a field your resource does not have, and it will only fail once that code runs.
+
+`@zap-studio/permit` keeps all rules in one place, through `createPolicy(...)` with `allow()`, `deny()`, and `when(condition)` — one file answers "who can do what."
+
+And because resources come from your Standard Schema schemas, policy types are derived straight from your real data shapes. Reference a field that does not exist, and you get an error while writing the code, not a silent `undefined` in production.
+
 ## Installation
 
 ```bash
@@ -21,12 +31,14 @@ You also need a schema library that implements [Standard Schema](https://standar
 - **Composable conditions** via `and`, `or`, and `not`.
 - **Policy merging strategies** via `mergePoliciesAnd` and `mergePoliciesOr`.
 - **Structured errors** with `PolicyError` for invalid configuration or evaluation failures.
+- **Optional logging** through `createPolicy({ logger })` ([`@zap-studio/logger`](https://www.npmjs.com/package/@zap-studio/logger)) — omit it and there's zero added logging overhead.
 - **Tree-shakeable** — policies and conditions are plain functions; unused exports are dropped by any modern bundler.
 
 ## Quick Start
 
 ```ts
 import { z } from "zod";
+import { ConsoleLogger } from "@zap-studio/logger";
 import { createPolicy, allow, deny, when } from "@zap-studio/permit";
 import type { Resources, Actions } from "@zap-studio/permit";
 
@@ -40,6 +52,8 @@ const actions = {
 
 type AppContext = { user: { id: string } };
 
+const logger = new ConsoleLogger({ minLevel: "debug" });
+
 const policy = createPolicy<AppContext>({
   resources,
   actions,
@@ -50,6 +64,7 @@ const policy = createPolicy<AppContext>({
       delete: deny(),
     },
   },
+  logger,
 });
 
 const ctx: AppContext = { user: { id: "user-1" } };
@@ -131,6 +146,20 @@ try {
 }
 ```
 
+## Logging
+
+Pass a `logger?: Logger` from [`@zap-studio/logger`](https://www.npmjs.com/package/@zap-studio/logger) to `createPolicy(...)` to observe allow/deny decisions. Omit it and only the pre-existing internal-error warnings still print, unchanged.
+
+```ts
+import { ConsoleLogger } from "@zap-studio/logger";
+import { createPolicy } from "@zap-studio/permit";
+
+const logger = new ConsoleLogger({ minLevel: "debug" });
+const policy = createPolicy({ resources, actions, rules, logger });
+```
+
+Allow decisions log at `debug`, deny decisions log at `info`. Resource validation and policy evaluation errors log at `warn` through the logger when one is provided, instead of `console.warn`.
+
 ## Runtime Support
 
 | Runtime            | Minimum version                                  |

package/dist/policy.d.ts.map

@@ -1 +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"}
+{"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;;;;;;;;;;;;;;;cAoKnB,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

@@ -71,7 +71,7 @@ const parsePermission = (permission, actions) => {
 * ```
 */
 const createPolicy = (config) => {
-	const { rules, resources, actions } = config;
+	const { rules, resources, actions, logger } = config;
 	const validators = /* @__PURE__ */ new Map();
 	const getValidatedResource = async (resourceType, resource) => {
 		const validator = validators.get(resourceType);
@@ -81,7 +81,10 @@ const createPolicy = (config) => {
 			if (result.issues) return null;
 			return result.value;
 		} catch (error) {
-			console.warn(`Resource validation failed for ${String(resourceType)}: ${String(error)}`);
+			logger?.warn(`Resource validation failed for ${String(resourceType)}: ${String(error)}`, {
+				error,
+				resourceType: String(resourceType)
+			});
 			return null;
 		}
 	};
@@ -90,9 +93,22 @@ const createPolicy = (config) => {
 		const policyFn = rules[resourceType]?.[action];
 		if (policyFn === void 0) return false;
 		try {
-			return policyFn(context, action, resource) === "allow";
+			const allowed = policyFn(context, action, resource) === "allow";
+			if (allowed) logger?.debug("permission allowed", {
+				action,
+				resourceType: String(resourceType)
+			});
+			else logger?.info("permission denied", {
+				action,
+				resourceType: String(resourceType)
+			});
+			return allowed;
 		} catch (error) {
-			console.warn(`Policy evaluation error for ${String(resourceType)}.${action}: ${String(error)}`);
+			logger?.warn(`Policy evaluation error for ${String(resourceType)}.${action}: ${String(error)}`, {
+				action,
+				error,
+				resourceType: String(resourceType)
+			});
 			return false;
 		}
 	};

package/dist/policy.js.map

@@ -1 +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"}
+{"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, logger } = 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      logger?.warn(\n        `Resource validation failed for ${String(resourceType)}: ${String(error)}`,\n        { error, resourceType: String(resourceType) }\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      const allowed = policyFn(context, action, resource) === \"allow\";\n\n      if (allowed) {\n        logger?.debug(\"permission allowed\", {\n          action,\n          resourceType: String(resourceType),\n        });\n      } else {\n        logger?.info(\"permission denied\", {\n          action,\n          resourceType: String(resourceType),\n        });\n      }\n\n      return allowed;\n    } catch (error) {\n      logger?.warn(\n        `Policy evaluation error for ${String(resourceType)}.${action}: ${String(error)}`,\n        {\n          action,\n          error,\n          resourceType: String(resourceType),\n        }\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":"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"}

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import { StandardSchemaV1 } from "@zap-studio/validation";
+import { Logger } from "@zap-studio/logger";
 //#region src/types.d.ts
 /**
  * Represents the possible outcomes of a policy decision.
@@ -130,9 +131,21 @@ type ConditionFn<TContext extends Context, TAction extends string = string, TRes
  * Call signatures for {@link hasRole}, preserving the with/without hierarchy overloads.
  */
 interface HasRoleFn {
+  /**
+   * Checks membership in `role` only, with no inherited roles.
+   *
+   * @param role - Role the context's `role` (or `role[]`) must include.
+   */
   <TContext extends {
     role: Role | Role[];
   }, TAction extends string = string, TResource = unknown>(role: Role): ConditionFn<TContext, TAction, TResource>;
+  /**
+   * Checks membership in `role`, treating any role that inherits from it
+   * (per `hierarchy`) as also satisfying the check.
+   *
+   * @param role - Role the context's `role` (or `role[]`) must include or inherit.
+   * @param hierarchy - Maps each role to the roles it inherits from.
+   */
   <TContext extends {
     role: TRole | TRole[];
   }, TAction extends string = string, TResource = unknown, TRole extends Role = Role>(role: TRole, hierarchy: RoleHierarchy<TRole>): ConditionFn<TContext, TAction, TResource>;
@@ -190,8 +203,27 @@ type Rules<TContext extends Context, TResources extends Resources = Resources, T
  * ```
  */
 interface PermitConfig<TContext extends Context, TResources extends Resources = Resources, TActions extends Actions<TResources> = Actions<TResources>> {
+  /**
+   * Allowed actions per resource type. Determines which `resource:action`
+   * permission strings are valid to check with `Policy.can(...)`.
+   */
   actions: TActions;
+  /**
+   * Optional logger for policy evaluation internals. When omitted, nothing
+   * is logged.
+   *
+   * Logs allow decisions at `debug` and deny decisions at `info`.
+   */
+  logger?: Logger;
+  /**
+   * Standard Schema resource definitions, keyed by resource type. Each
+   * resource is validated against its schema before rules are evaluated.
+   */
   resources: TResources;
+  /**
+   * Policy functions for each resource/action combination, deciding
+   * `"allow"` or `"deny"` for a given context and resource.
+   */
   rules: Rules<TContext, TResources, TActions>;
 }
 /**

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","names":[],"sources":["../src/types.ts"],"mappings":";;;;;;;;;;;;KAkBY;;;;;;;;;;KAWA,QAAQ,sBAAsB;;;;;;;;;KAU9B,KAAK,iCAAiC;;;;;;;;;;;;;;;;KAiBtC,cAAc,cAAc,OAAO,QAAQ,OAAO,OAAO;;;;;;;;;;;;;;;;KAiBzD,UAAU,wCAAwC,OAC5D,cACA;;;;;;;;;;;;;;;KAiBU,QAAQ,mBAAmB,gBACpC,WAAW;;;;;;;;;KAWF,cACV,mBAAmB,WACnB,2BAA2B,cACzB,iBAAiB,YAAY,WAAW;;;;;;;;;;KAWhC,YACV,mBAAmB,WACnB,iBAAiB,QAAQ,aACzB,gBAAgB,YACd,SAAS;;;;;;;;;;KAWD,gBACV,mBAAmB,WACnB,iBAAiB,QAAQ,kBAGvB,WAAW,mBAAmB,cAC1B,cAAc,YAAY,YAAY,UAAU,uBAChD,mBAAmB;;;;;;;;;;KAWf,SACV,iBAAiB,SACjB,iCACA,wBACG,SAAS,UAAU,QAAQ,SAAS,UAAU,cAAc;;;;;;;;;;KAWrD,YACV,iBAAiB,SACjB,iCACA,wBACG,SAAS,UAAU,QAAQ,SAAS,UAAU;;;;UAKlC;GAEb;IAAmB,MAAM,OAAO;KAChC,iCACA,qBAEA,MAAM,OACL,YAAY,UAAU,SAAS;GAEhC;IAAmB,MAAM,QAAQ;KACjC,iCACA,qBACA,cAAc,OAAO,MAErB,MAAM,OACN,WAAW,cAAc,SACxB,YAAY,UAAU,SAAS;;;;;;;;;;;;;;;;;;KAmBxB,gBACV,iBAAiB,SACjB,iCACA,0BAEC,KAAK,WAAW,SAAS,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;KAuB7B,MACV,iBAAiB,SACjB,mBAAmB,YAAY,WAC/B,iBAAiB,QAAQ,cAAc,QAAQ,kBAE9C,WAAW,mBAAmB,WAAW,gBACxC,UACA,YAAY,YAAY,UAAU,IAClC,cAAc,YAAY;;;;;;;;;;;;;;;UAkBb,aACf,iBAAiB,SACjB,mBAAmB,YAAY,WAC/B,iBAAiB,QAAQ,cAAc,QAAQ;EAE/C,SAAS;EACT,WAAW;EACX,OAAO,MAAM,UAAU,YAAY;;;;;;;;;;;;;;;;;UAkBpB,OACf,iBAAiB,SACjB,mBAAmB,YAAY,WAC/B,iBAAiB,QAAQ,cAAc,QAAQ;;;;EAK/C,MAAM,gBAAgB,mBAAmB,UACvC,SAAS,UACT,eAAe,cAAc,YAAY,YAAY,UAAU,eAC/D,UAAU,cAAc,YAAY,OACjC"}
+{"version":3,"file":"types.d.ts","names":[],"sources":["../src/types.ts"],"mappings":";;;;;;;;;;;;;KAmBY;;;;;;;;;;KAWA,QAAQ,sBAAsB;;;;;;;;;KAU9B,KAAK,iCAAiC;;;;;;;;;;;;;;;;KAiBtC,cAAc,cAAc,OAAO,QAAQ,OAAO,OAAO;;;;;;;;;;;;;;;;KAiBzD,UAAU,wCAAwC,OAC5D,cACA;;;;;;;;;;;;;;;KAiBU,QAAQ,mBAAmB,gBACpC,WAAW;;;;;;;;;KAWF,cACV,mBAAmB,WACnB,2BAA2B,cACzB,iBAAiB,YAAY,WAAW;;;;;;;;;;KAWhC,YACV,mBAAmB,WACnB,iBAAiB,QAAQ,aACzB,gBAAgB,YACd,SAAS;;;;;;;;;;KAWD,gBACV,mBAAmB,WACnB,iBAAiB,QAAQ,kBAGvB,WAAW,mBAAmB,cAC1B,cAAc,YAAY,YAAY,UAAU,uBAChD,mBAAmB;;;;;;;;;;KAWf,SACV,iBAAiB,SACjB,iCACA,wBACG,SAAS,UAAU,QAAQ,SAAS,UAAU,cAAc;;;;;;;;;;KAWrD,YACV,iBAAiB,SACjB,iCACA,wBACG,SAAS,UAAU,QAAQ,SAAS,UAAU;;;;UAKlC;;;;;;GAOb;IAAmB,MAAM,OAAO;KAChC,iCACA,qBAEA,MAAM,OACL,YAAY,UAAU,SAAS;;;;;;;;GAShC;IAAmB,MAAM,QAAQ;KACjC,iCACA,qBACA,cAAc,OAAO,MAErB,MAAM,OACN,WAAW,cAAc,SACxB,YAAY,UAAU,SAAS;;;;;;;;;;;;;;;;;;KAmBxB,gBACV,iBAAiB,SACjB,iCACA,0BAEC,KAAK,WAAW,SAAS,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;KAuB7B,MACV,iBAAiB,SACjB,mBAAmB,YAAY,WAC/B,iBAAiB,QAAQ,cAAc,QAAQ,kBAE9C,WAAW,mBAAmB,WAAW,gBACxC,UACA,YAAY,YAAY,UAAU,IAClC,cAAc,YAAY;;;;;;;;;;;;;;;UAkBb,aACf,iBAAiB,SACjB,mBAAmB,YAAY,WAC/B,iBAAiB,QAAQ,cAAc,QAAQ;;;;;EAM/C,SAAS;;;;;;;EAOT,SAAS;;;;;EAKT,WAAW;;;;;EAKX,OAAO,MAAM,UAAU,YAAY;;;;;;;;;;;;;;;;;UAkBpB,OACf,iBAAiB,SACjB,mBAAmB,YAAY,WAC/B,iBAAiB,QAAQ,cAAc,QAAQ;;;;EAK/C,MAAM,gBAAgB,mBAAmB,UACvC,SAAS,UACT,eAAe,cAAc,YAAY,YAAY,UAAU,eAC/D,UAAU,cAAc,YAAY,OACjC"}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@zap-studio/permit",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "private": false,
-  "description": "A type-safe, declarative, tree-shakeable authorization library for TypeScript with Standard Schema support",
+  "description": "A type-safe, declarative, tree-shakeable authorization library for TypeScript with Standard Schema support.",
   "keywords": [
     "abac",
     "access-control",
@@ -50,8 +50,17 @@
     "tsdown": "^0.22.14",
     "typescript": "^7.0.2",
     "vitest": "^4.1.10",
+    "@zap-studio/logger": "1.0.0",
     "@zap-studio/typescript": "0.0.0"
   },
+  "peerDependencies": {
+    "@zap-studio/logger": "1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@zap-studio/logger": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": ">=18.0.0"
   }