@zap-studio/permit 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @zap-studio/permit
 
+## 0.2.2
+
+### Patch Changes
+
+- e26293e: Updated dependencies.
+  - @zap-studio/validation@0.3.2
+
 ## 0.2.1
 
 ### Patch Changes
@@ -7,7 +14,6 @@
 - 5ea3d3b: Updated dependencies.
   - @zap-studio/validation@0.3.1
 
-
 ## 0.2.0
 
 ### Changed

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.1",
+  "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.1"
+    "@zap-studio/validation": "0.3.2"
   },
   "devDependencies": {
     "@types/node": "^25.0.2",
@@ -57,6 +60,9 @@
   "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",
     "typecheck": "tsc --noEmit",

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.