@zap-studio/permit 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -1,57 +1,69 @@
 # @zap-studio/permit
 
-## 0.2.0
+## 0.2.2
 
-### Minor Changes
+### Patch Changes
 
-- f0f503e: Make policy evaluation async by default.
+- e26293e: Updated dependencies.
+  - @zap-studio/validation@0.3.2
 
-  `policy.can(...)` now returns a `Promise<boolean>` and must be awaited.
+## 0.2.1
 
-  `createPolicy` now uses async-safe Standard Schema validation internally, so resource schemas with async validation are supported.
+### Patch Changes
 
-  `mergePolicies` and `mergePoliciesAny` are also async through the shared `Policy` interface.
+- 5ea3d3b: Updated dependencies.
+  - @zap-studio/validation@0.3.1
 
-### Patch Changes
+## 0.2.0
+
+### Changed
+
+- f0f503e: Made policy evaluation asynchronous by default.
+
+### Breaking Changes
+
+- f0f503e: `policy.can(...)` now returns `Promise<boolean>`.
+- f0f503e: `createPolicy()` now uses async-safe Standard Schema validation for resource schemas (including async resource schemas); this is not a separate `Policy` schema API.
+- f0f503e: The `Policy` interface changed so `can()` is async, and `mergePolicies`/`mergePoliciesAny` are async accordingly.
+- Action required: callers must `await policy.can(...)` and handle `mergePolicies`/`mergePoliciesAny` as async operations; also account for async-safe resource schema validation in `createPolicy()`.
 
-- Updated dependencies [f75b984]
-  - @zap-studio/validation@0.3.0
+### Dependencies
+
+- f75b984: Updated dependency `@zap-studio/validation` to `0.3.0`.
 
 ## 0.1.3
 
-### Patch Changes
+### Dependencies
 
-- Updated dependencies [e4542bb]
-  - @zap-studio/validation@0.2.1
+- e4542bb: Updated dependency `@zap-studio/validation` to `0.2.1`.
 
 ## 0.1.2
 
-### Patch Changes
+### Changed
 
-- 2de8183: Add a reusable synchronous Standard Schema validator helper in `@zap-studio/validation` and refactor `@zap-studio/permit` to use it for resource schema validation in `createPolicy`.
-- Updated dependencies [2de8183]
-  - @zap-studio/validation@0.2.0
+- 2de8183: Adopted shared synchronous Standard Schema validator utilities from `@zap-studio/validation` for resource schema validation in `createPolicy`.
 
-## 0.1.1
+### Dependencies
 
-### Patch Changes
+- 2de8183: Updated dependency `@zap-studio/validation` to `0.2.0`.
 
-- 907d903: Add runtime resource validation and fail-closed behavior, including denying access when merges are called with no policies.
-
-## 0.1.0
+## 0.1.1
 
-### Minor Changes
+### Fixed
 
-- 0627885: Initial release of @zap-studio/permit - a type-safe, declarative authorization library for TypeScript.
+- 907d903: Added runtime resource validation and fail-closed behavior, including deny-by-default when merges are invoked with no policies.
 
-  Features:
+## 0.1.0
 
-  - Declarative policy creation with `createPolicy()`
-  - Policy rules: `allow()`, `deny()`, and `when()` for conditional access
-  - Condition combinators: `and()`, `or()`, `not()`, and `has()`
-  - Role-based access control with `hasRole()` and role hierarchies
-  - Policy merging with `mergePolicies()` (deny-overrides) and `mergePoliciesAny()` (allow-overrides)
-  - Standard Schema support (Zod, Valibot, ArkType, etc.)
-  - Full TypeScript support with type inference
-  - `PolicyError` class for authorization errors
-  - `assertNever()` helper for exhaustive type checking
+### Added
+
+- 0627885: Initial release of `@zap-studio/permit`.
+  - Declarative policy creation with `createPolicy()`.
+  - Policy rules: `allow()`, `deny()`, and `when()` for conditional access.
+  - Condition combinators: `and()`, `or()`, `not()`, and `has()`.
+  - Role-based access control with `hasRole()` and role hierarchies.
+  - Policy merging with `mergePolicies()` (deny-overrides) and `mergePoliciesAny()` (allow-overrides).
+  - Standard Schema support (Zod, Valibot, ArkType, and more).
+  - Full TypeScript type inference support.
+  - `PolicyError` for authorization failures.
+  - `assertNever()` for exhaustive checks.

package/bin/intent.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// Auto-generated by @tanstack/intent setup
+// Exposes the intent end-user CLI for consumers of this library.
+await import("@tanstack/intent/intent-library");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zap-studio/permit",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "type": "module",
   "license": "MIT",
   "private": false,
@@ -30,12 +30,15 @@
   "files": [
     "dist",
     "CHANGELOG.md",
-    "LICENSE.md",
-    "README.md"
+    "LICENSE",
+    "README.md",
+    "skills",
+    "bin",
+    "!skills/_artifacts"
   ],
   "dependencies": {
     "@standard-schema/spec": "^1.1.0",
-    "@zap-studio/validation": "0.3.0"
+    "@zap-studio/validation": "0.3.2"
   },
   "devDependencies": {
     "@types/node": "^25.0.2",
@@ -43,9 +46,9 @@
     "tsdown": "^0.18.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18",
+    "@zap-studio/vitest-config": "0.0.0",
     "@zap-studio/typescript-config": "0.0.0",
-    "@zap-studio/tsdown-config": "0.0.0",
-    "@zap-studio/vitest-config": "0.0.0"
+    "@zap-studio/tsdown-config": "0.0.0"
   },
   "exports": {
     ".": "./dist/index.mjs",
@@ -57,9 +60,12 @@
   "main": "./dist/index.mjs",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
+  "bin": {
+    "intent": "./bin/intent.js"
+  },
   "scripts": {
     "build": "tsdown --config tsdown.config.ts",
-    "check": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest --watch"
   }

package/skills/zap-permit-policy-authoring/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: zap-permit-policy-authoring
+description: >
+  Author typed authorization policies with @zap-studio/permit using
+  createPolicy, allow/deny/when, condition combinators, has/hasRole,
+  and mergePolicies vs mergePoliciesAny decision strategies.
+type: core
+library: '@zap-studio/permit'
+library_version: '0.2.1'
+sources:
+  - 'zap-studio/monorepo:packages/permit/README.md'
+  - 'zap-studio/monorepo:packages/permit/src/index.ts'
+  - 'zap-studio/monorepo:packages/permit/src/types.ts'
+---
+
+# @zap-studio/permit — Policy Authoring
+
+## Setup
+
+```ts
+import { z } from 'zod';
+import { createPolicy, allow, when } from '@zap-studio/permit';
+import type { Resources, Actions } from '@zap-studio/permit/types';
+
+const resources = {
+  post: z.object({ id: z.string(), authorId: z.string() }),
+} satisfies Resources;
+
+const actions = {
+  post: ['read', 'write'],
+} as const satisfies Actions<typeof resources>;
+
+type AppContext = { user: { id: string; role: 'user' | 'admin' } };
+
+const policy = createPolicy<AppContext>({
+  resources,
+  actions,
+  rules: {
+    post: {
+      read: allow(),
+      write: when((ctx, _action, post) => ctx.user.id === post.authorId),
+    },
+  },
+});
+```
+
+## Core Patterns
+
+### Compose conditions with `and`, `or`, and `not`
+
+```ts
+import { when, and, or, not } from '@zap-studio/permit';
+
+const canEdit = when(
+  and(
+    (ctx, _action, post) => ctx.user.id === post.authorId,
+    not((_ctx, _action, post) => post.locked === true),
+  ),
+);
+
+const canRead = when(
+  or(
+    (_ctx, _action, post) => post.visibility === 'public',
+    (ctx, _action, post) => ctx.user.id === post.authorId,
+  ),
+);
+```
+
+### Add role inheritance checks with `hasRole`
+
+```ts
+import { when, hasRole } from '@zap-studio/permit';
+
+const hierarchy = {
+  guest: [],
+  user: ['guest'],
+  admin: ['user'],
+} as const;
+
+const adminOnly = when(hasRole('admin', hierarchy));
+```
+
+### Choose merge strategy explicitly
+
+```ts
+import { mergePolicies, mergePoliciesAny } from '@zap-studio/permit';
+
+const strict = mergePolicies(basePolicy, tenantPolicy); // all must allow
+const permissive = mergePoliciesAny(basePolicy, temporaryOverridePolicy); // any can allow
+```
+
+## Common Mistakes
+
+### HIGH Using action missing from actions map
+
+Wrong:
+
+```ts
+await policy.can(ctx, 'publish', 'post', post);
+```
+
+Correct:
+
+```ts
+const actions = {
+  post: ['read', 'write', 'publish'],
+} as const;
+
+await policy.can(ctx, 'publish', 'post', post);
+```
+
+`can()` first checks `actions[resourceType]`; missing actions always resolve to `false`.
+
+Source: zap-studio/monorepo:packages/permit/src/index.ts
+
+### HIGH Assuming invalid resources still hit rule function
+
+Wrong:
+
+```ts
+await policy.can(ctx, 'write', 'post', { id: 123 } as any);
+```
+
+Correct:
+
+```ts
+await policy.can(ctx, 'write', 'post', {
+  id: '123',
+  authorId: ctx.user.id,
+});
+```
+
+Resource validation runs before policy evaluation; invalid payloads short-circuit to deny.
+
+Source: zap-studio/monorepo:packages/permit/src/index.ts
+
+### MEDIUM Expecting `mergePoliciesAny` to enforce deny-overrides
+
+Wrong:
+
+```ts
+const merged = mergePoliciesAny(basePolicy, restrictivePolicy);
+// expecting restrictivePolicy to always win
+```
+
+Correct:
+
+```ts
+const merged = mergePolicies(basePolicy, restrictivePolicy);
+// deny-overrides behavior
+```
+
+`mergePoliciesAny` returns allowed when any policy allows; use `mergePolicies` for strict composition.
+
+Source: zap-studio/monorepo:packages/permit/src/index.ts
+
+See also: zap-validation-standard-schema/SKILL.md — invalid resource payload behavior.