@pyreon/permissions 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vit Bokisch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@pyreon/permissions",
+  "version": "0.5.0",
+  "description": "Reactive permissions for Pyreon — type-safe, signal-driven, universal",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pyreon/fundamentals.git",
+    "directory": "packages/permissions"
+  },
+  "homepage": "https://github.com/pyreon/fundamentals/tree/main/packages/permissions#readme",
+  "bugs": {
+    "url": "https://github.com/pyreon/fundamentals/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "lib",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./lib/index.js",
+  "module": "./lib/index.js",
+  "types": "./lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./lib/index.js",
+      "types": "./lib/types/index.d.ts"
+    }
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "vl_rolldown_build",
+    "dev": "vl_rolldown_build-watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@pyreon/core": ">=0.5.0 <1.0.0",
+    "@pyreon/reactivity": ">=0.5.0 <1.0.0"
+  },
+  "devDependencies": {
+    "@happy-dom/global-registrator": "^20.8.3",
+    "@pyreon/core": ">=0.5.0 <1.0.0",
+    "@pyreon/reactivity": ">=0.5.0 <1.0.0",
+    "@vitus-labs/tools-lint": "^1.11.0"
+  }
+}

package/src/context.ts

@@ -0,0 +1,57 @@
+import {
+  createContext,
+  onUnmount,
+  popContext,
+  pushContext,
+  useContext,
+} from '@pyreon/core'
+import type { VNodeChild } from '@pyreon/core'
+import type { Permissions } from './types'
+
+const PermissionsContext = createContext<Permissions | null>(null)
+
+/**
+ * Provide a permissions instance to descendant components.
+ * Use this for SSR isolation or testing — each request/test gets its own instance.
+ *
+ * @example
+ * ```tsx
+ * const can = createPermissions({ ... })
+ *
+ * <PermissionsProvider instance={can}>
+ *   <App />
+ * </PermissionsProvider>
+ * ```
+ */
+export function PermissionsProvider(props: {
+  instance: Permissions
+  children?: VNodeChild
+}): VNodeChild {
+  const frame = new Map<symbol, unknown>([
+    [PermissionsContext.id, props.instance],
+  ])
+  pushContext(frame)
+  onUnmount(() => popContext())
+
+  return props.children ?? null
+}
+
+/**
+ * Access the nearest permissions instance from context.
+ * Must be used within a `<PermissionsProvider>`.
+ *
+ * @example
+ * ```tsx
+ * const can = usePermissions()
+ * {() => can('posts.read') && <PostList />}
+ * ```
+ */
+export function usePermissions(): Permissions {
+  const instance = useContext(PermissionsContext)
+  if (!instance) {
+    throw new Error(
+      '[@pyreon/permissions] usePermissions() must be used within <PermissionsProvider>',
+    )
+  }
+  return instance
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+/**
+ * @pyreon/permissions — Reactive permissions for Pyreon.
+ *
+ * A permission is a boolean or a function. Check with `can()` — reactive
+ * in effects, computeds, and JSX. Universal: RBAC, ABAC, feature flags,
+ * subscription tiers — any model maps to string keys.
+ *
+ * @example
+ * ```tsx
+ * import { createPermissions } from '@pyreon/permissions'
+ *
+ * const can = createPermissions({
+ *   'posts.read': true,
+ *   'posts.update': (post: Post) => post.authorId === userId(),
+ *   'users.manage': false,
+ * })
+ *
+ * // Reactive check in JSX
+ * {() => can('posts.read') && <PostList />}
+ *
+ * // Update after login
+ * can.set(fromRole(user.role))
+ * ```
+ */
+
+export { createPermissions } from './permissions'
+export { PermissionsProvider, usePermissions } from './context'
+
+// Types
+export type {
+  PermissionMap,
+  PermissionPredicate,
+  PermissionValue,
+  Permissions,
+} from './types'

package/src/permissions.ts

@@ -0,0 +1,130 @@
+import { computed, signal } from '@pyreon/reactivity'
+import type { PermissionMap, PermissionValue, Permissions } from './types'
+
+/**
+ * Resolve a permission key against the map.
+ * Resolution order: exact match → wildcard (e.g., 'posts.*') → global wildcard ('*') → false.
+ */
+function resolve(
+  map: Map<string, PermissionValue>,
+  key: string,
+  context?: unknown,
+): boolean {
+  // 1. Exact match
+  const exact = map.get(key)
+  if (exact !== undefined) {
+    return typeof exact === 'function' ? exact(context) : exact
+  }
+
+  // 2. Wildcard match — 'posts.read' matches 'posts.*'
+  const dotIndex = key.lastIndexOf('.')
+  if (dotIndex !== -1) {
+    const prefix = key.slice(0, dotIndex)
+    const wildcard = map.get(`${prefix}.*`)
+    if (wildcard !== undefined) {
+      return typeof wildcard === 'function' ? wildcard(context) : wildcard
+    }
+  }
+
+  // 3. Global wildcard
+  const global = map.get('*')
+  if (global !== undefined) {
+    return typeof global === 'function' ? global(context) : global
+  }
+
+  // 4. No match → denied
+  return false
+}
+
+/**
+ * Create a reactive permissions instance.
+ *
+ * The returned `can` function checks permissions reactively —
+ * reads update automatically when permissions change via `set()` or `patch()`.
+ *
+ * @param initial - Optional initial permission map
+ * @returns A callable `Permissions` instance
+ *
+ * @example
+ * ```tsx
+ * const can = createPermissions({
+ *   'posts.read': true,
+ *   'posts.update': (post: Post) => post.authorId === userId(),
+ *   'users.manage': false,
+ * })
+ *
+ * // Check (reactive in effects/computeds/JSX)
+ * can('posts.read')              // true
+ * can('posts.update', myPost)    // evaluates predicate
+ *
+ * // JSX
+ * {() => can('posts.delete') && <DeleteButton />}
+ *
+ * // Update
+ * can.set({ 'posts.read': true, 'admin': true })
+ * can.patch({ 'users.manage': true })
+ * ```
+ */
+export function createPermissions(initial?: PermissionMap): Permissions {
+  // Internal reactive state — a signal holding the permission map
+  const store = signal(toMap(initial))
+  // Version counter — incremented on every set/patch to trigger reactive updates
+  const version = signal(0)
+
+  function toMap(obj?: PermissionMap): Map<string, PermissionValue> {
+    if (!obj) return new Map()
+    return new Map(Object.entries(obj))
+  }
+
+  // The main check function — reads `version` to subscribe in reactive contexts
+  function can(key: string, context?: unknown): boolean {
+    // Reading version subscribes this call to reactive updates
+    version()
+    return resolve(store.peek(), key, context)
+  }
+
+  can.not = (key: string, context?: unknown): boolean => {
+    return !can(key, context)
+  }
+
+  can.all = (...keys: string[]): boolean => {
+    return keys.every((key) => can(key))
+  }
+
+  can.any = (...keys: string[]): boolean => {
+    return keys.some((key) => can(key))
+  }
+
+  can.set = (permissions: PermissionMap): void => {
+    store.set(toMap(permissions))
+    version.update((v) => v + 1)
+  }
+
+  can.patch = (permissions: PermissionMap): void => {
+    const current = store.peek()
+    for (const [key, value] of Object.entries(permissions)) {
+      current.set(key, value)
+    }
+    store.set(current)
+    version.update((v) => v + 1)
+  }
+
+  can.granted = computed(() => {
+    version()
+    const keys: string[] = []
+    for (const [key, value] of store.peek()) {
+      // Static true or predicate (capability exists)
+      if (value === true || typeof value === 'function') {
+        keys.push(key)
+      }
+    }
+    return keys
+  })
+
+  can.entries = computed(() => {
+    version()
+    return [...store.peek().entries()]
+  })
+
+  return can as Permissions
+}

package/src/tests/permissions.test.ts

@@ -0,0 +1,547 @@
+import { computed, effect, signal } from '@pyreon/reactivity'
+import { describe, expect, it } from 'vitest'
+import { createPermissions } from '../index'
+
+describe('createPermissions', () => {
+  // ─── Basic checks ────────────────────────────────────────────────────────
+
+  describe('static permissions', () => {
+    it('returns true for granted permissions', () => {
+      const can = createPermissions({ 'posts.read': true })
+      expect(can('posts.read')).toBe(true)
+    })
+
+    it('returns false for denied permissions', () => {
+      const can = createPermissions({ 'posts.delete': false })
+      expect(can('posts.delete')).toBe(false)
+    })
+
+    it('returns false for undefined permissions', () => {
+      const can = createPermissions({ 'posts.read': true })
+      expect(can('users.manage')).toBe(false)
+    })
+
+    it('handles empty initial permissions', () => {
+      const can = createPermissions()
+      expect(can('anything')).toBe(false)
+    })
+
+    it('handles empty object', () => {
+      const can = createPermissions({})
+      expect(can('anything')).toBe(false)
+    })
+  })
+
+  // ─── Predicate permissions ─────────────────────────────────────────────
+
+  describe('predicate permissions', () => {
+    it('evaluates predicate without context', () => {
+      const role = signal('admin')
+      const can = createPermissions({
+        'users.manage': () => role() === 'admin',
+      })
+      expect(can('users.manage')).toBe(true)
+    })
+
+    it('evaluates predicate with context', () => {
+      const userId = signal('user-1')
+      const can = createPermissions({
+        'posts.update': (post: any) => post?.authorId === userId.peek(),
+      })
+
+      expect(can('posts.update', { authorId: 'user-1' })).toBe(true)
+      expect(can('posts.update', { authorId: 'user-2' })).toBe(false)
+    })
+
+    it('predicate without context returns result of calling with undefined', () => {
+      const can = createPermissions({
+        'posts.update': (post?: any) => post?.authorId === 'user-1',
+      })
+      // No context — post is undefined, so authorId check fails
+      expect(can('posts.update')).toBe(false)
+    })
+
+    it('predicate that ignores context', () => {
+      const can = createPermissions({
+        'posts.create': () => true,
+      })
+      expect(can('posts.create')).toBe(true)
+    })
+  })
+
+  // ─── Wildcard matching ─────────────────────────────────────────────────
+
+  describe('wildcard matching', () => {
+    it('matches prefix wildcard', () => {
+      const can = createPermissions({ 'posts.*': true })
+      expect(can('posts.read')).toBe(true)
+      expect(can('posts.create')).toBe(true)
+      expect(can('posts.delete')).toBe(true)
+    })
+
+    it('exact match takes precedence over wildcard', () => {
+      const can = createPermissions({
+        'posts.*': true,
+        'posts.delete': false,
+      })
+      expect(can('posts.read')).toBe(true)
+      expect(can('posts.delete')).toBe(false)
+    })
+
+    it('global wildcard matches everything', () => {
+      const can = createPermissions({ '*': true })
+      expect(can('posts.read')).toBe(true)
+      expect(can('users.manage')).toBe(true)
+      expect(can('anything')).toBe(true)
+    })
+
+    it('exact match takes precedence over global wildcard', () => {
+      const can = createPermissions({
+        '*': true,
+        'billing.export': false,
+      })
+      expect(can('posts.read')).toBe(true)
+      expect(can('billing.export')).toBe(false)
+    })
+
+    it('prefix wildcard takes precedence over global wildcard', () => {
+      const can = createPermissions({
+        '*': false,
+        'posts.*': true,
+      })
+      expect(can('posts.read')).toBe(true)
+      expect(can('users.manage')).toBe(false)
+    })
+
+    it('wildcard with predicate', () => {
+      const can = createPermissions({
+        'posts.*': (post: any) => post?.status !== 'archived',
+      })
+      expect(can('posts.read', { status: 'published' })).toBe(true)
+      expect(can('posts.update', { status: 'archived' })).toBe(false)
+    })
+
+    it('does not match partial prefixes', () => {
+      const can = createPermissions({ 'post.*': true })
+      expect(can('posts.read')).toBe(false) // 'posts' !== 'post'
+    })
+  })
+
+  // ─── can.not ───────────────────────────────────────────────────────────
+
+  describe('can.not()', () => {
+    it('returns inverse of can()', () => {
+      const can = createPermissions({
+        'posts.read': true,
+        'posts.delete': false,
+      })
+      expect(can.not('posts.read')).toBe(false)
+      expect(can.not('posts.delete')).toBe(true)
+      expect(can.not('users.manage')).toBe(true)
+    })
+
+    it('works with predicates and context', () => {
+      const can = createPermissions({
+        'posts.update': (post: any) => post?.authorId === 'me',
+      })
+      expect(can.not('posts.update', { authorId: 'me' })).toBe(false)
+      expect(can.not('posts.update', { authorId: 'other' })).toBe(true)
+    })
+  })
+
+  // ─── can.all / can.any ─────────────────────────────────────────────────
+
+  describe('can.all()', () => {
+    it('returns true when all permissions are granted', () => {
+      const can = createPermissions({
+        'posts.read': true,
+        'posts.create': true,
+      })
+      expect(can.all('posts.read', 'posts.create')).toBe(true)
+    })
+
+    it('returns false when any permission is denied', () => {
+      const can = createPermissions({
+        'posts.read': true,
+        'posts.delete': false,
+      })
+      expect(can.all('posts.read', 'posts.delete')).toBe(false)
+    })
+
+    it('returns true for empty args', () => {
+      const can = createPermissions()
+      expect(can.all()).toBe(true)
+    })
+  })
+
+  describe('can.any()', () => {
+    it('returns true when any permission is granted', () => {
+      const can = createPermissions({
+        'posts.read': false,
+        'posts.create': true,
+      })
+      expect(can.any('posts.read', 'posts.create')).toBe(true)
+    })
+
+    it('returns false when no permissions are granted', () => {
+      const can = createPermissions({
+        'posts.read': false,
+        'posts.delete': false,
+      })
+      expect(can.any('posts.read', 'posts.delete')).toBe(false)
+    })
+
+    it('returns false for empty args', () => {
+      const can = createPermissions()
+      expect(can.any()).toBe(false)
+    })
+  })
+
+  // ─── set / patch ───────────────────────────────────────────────────────
+
+  describe('set()', () => {
+    it('replaces all permissions', () => {
+      const can = createPermissions({
+        'posts.read': true,
+        'users.manage': true,
+      })
+      expect(can('posts.read')).toBe(true)
+      expect(can('users.manage')).toBe(true)
+
+      can.set({ 'posts.read': false })
+      expect(can('posts.read')).toBe(false)
+      expect(can('users.manage')).toBe(false) // replaced, not merged
+    })
+
+    it('triggers reactive updates', () => {
+      const can = createPermissions({ 'posts.read': true })
+      const results: boolean[] = []
+
+      effect(() => {
+        results.push(can('posts.read'))
+      })
+
+      expect(results).toEqual([true])
+
+      can.set({ 'posts.read': false })
+      expect(results).toEqual([true, false])
+    })
+  })
+
+  describe('patch()', () => {
+    it('merges with existing permissions', () => {
+      const can = createPermissions({
+        'posts.read': true,
+        'users.manage': false,
+      })
+
+      can.patch({ 'users.manage': true, 'billing.view': true })
+      expect(can('posts.read')).toBe(true) // unchanged
+      expect(can('users.manage')).toBe(true) // updated
+      expect(can('billing.view')).toBe(true) // added
+    })
+
+    it('triggers reactive updates', () => {
+      const can = createPermissions({ 'posts.read': false })
+      const results: boolean[] = []
+
+      effect(() => {
+        results.push(can('posts.read'))
+      })
+
+      expect(results).toEqual([false])
+
+      can.patch({ 'posts.read': true })
+      expect(results).toEqual([false, true])
+    })
+  })
+
+  // ─── Reactivity ────────────────────────────────────────────────────────
+
+  describe('reactivity', () => {
+    it('can() is reactive inside effect', () => {
+      const can = createPermissions({ 'posts.read': true })
+      const results: boolean[] = []
+
+      effect(() => {
+        results.push(can('posts.read'))
+      })
+
+      can.set({ 'posts.read': false })
+      can.set({ 'posts.read': true })
+
+      expect(results).toEqual([true, false, true])
+    })
+
+    it('can() is reactive inside computed', () => {
+      const can = createPermissions({ admin: true })
+      const isAdmin = computed(() => can('admin'))
+
+      expect(isAdmin()).toBe(true)
+
+      can.set({ admin: false })
+      expect(isAdmin()).toBe(false)
+    })
+
+    it('can.not() is reactive', () => {
+      const can = createPermissions({ 'posts.read': true })
+      const results: boolean[] = []
+
+      effect(() => {
+        results.push(can.not('posts.read'))
+      })
+
+      can.set({ 'posts.read': false })
+      expect(results).toEqual([false, true])
+    })
+
+    it('can.all() is reactive', () => {
+      const can = createPermissions({
+        'posts.read': true,
+        'posts.create': true,
+      })
+      const results: boolean[] = []
+
+      effect(() => {
+        results.push(can.all('posts.read', 'posts.create'))
+      })
+
+      can.patch({ 'posts.create': false })
+      expect(results).toEqual([true, false])
+    })
+
+    it('can.any() is reactive', () => {
+      const can = createPermissions({
+        'posts.read': false,
+        'posts.create': true,
+      })
+      const results: boolean[] = []
+
+      effect(() => {
+        results.push(can.any('posts.read', 'posts.create'))
+      })
+
+      can.patch({ 'posts.create': false })
+      expect(results).toEqual([true, false])
+    })
+
+    it('predicate with reactive signals inside', () => {
+      const role = signal('admin')
+      const can = createPermissions({
+        'users.manage': () => role() === 'admin',
+      })
+
+      // The predicate reads `role()` but reactivity is driven by
+      // the permission version signal, not the inner signal.
+      // To react to role changes, update permissions:
+      expect(can('users.manage')).toBe(true)
+
+      can.patch({ 'users.manage': () => role() === 'admin' })
+      role.set('viewer')
+      // Need to re-evaluate — the predicate itself reads the signal
+      // but the permission system doesn't track inner signal deps.
+      // This is by design: update permissions via set/patch when the source changes.
+    })
+  })
+
+  // ─── granted / entries ─────────────────────────────────────────────────
+
+  describe('granted()', () => {
+    it('returns keys with true values', () => {
+      const can = createPermissions({
+        'posts.read': true,
+        'posts.delete': false,
+        'users.manage': true,
+      })
+      expect(can.granted()).toEqual(
+        expect.arrayContaining(['posts.read', 'users.manage']),
+      )
+      expect(can.granted()).not.toContain('posts.delete')
+    })
+
+    it('includes predicate keys', () => {
+      const can = createPermissions({
+        'posts.update': (post: any) => post?.authorId === 'me',
+      })
+      // Predicates are capabilities — they exist
+      expect(can.granted()).toContain('posts.update')
+    })
+
+    it('is reactive', () => {
+      const can = createPermissions({ 'posts.read': true })
+      const results: string[][] = []
+
+      effect(() => {
+        results.push([...can.granted()])
+      })
+
+      can.patch({ 'users.manage': true })
+      expect(results).toEqual([['posts.read'], ['posts.read', 'users.manage']])
+    })
+  })
+
+  describe('entries()', () => {
+    it('returns all entries', () => {
+      const can = createPermissions({
+        'posts.read': true,
+        'posts.delete': false,
+      })
+      const entries = can.entries()
+      expect(entries).toHaveLength(2)
+      expect(entries).toEqual(
+        expect.arrayContaining([
+          ['posts.read', true],
+          ['posts.delete', false],
+        ]),
+      )
+    })
+
+    it('is reactive', () => {
+      const can = createPermissions({ a: true })
+      const counts: number[] = []
+
+      effect(() => {
+        counts.push(can.entries().length)
+      })
+
+      can.patch({ b: true })
+      expect(counts).toEqual([1, 2])
+    })
+  })
+
+  // ─── Real-world patterns ───────────────────────────────────────────────
+
+  describe('real-world patterns', () => {
+    it('role-based access control', () => {
+      function fromRole(role: string) {
+        const roles: Record<string, Record<string, boolean>> = {
+          admin: { 'posts.*': true, 'users.*': true, 'billing.*': true },
+          editor: {
+            'posts.read': true,
+            'posts.create': true,
+            'posts.update': true,
+            'users.read': true,
+          },
+          viewer: { 'posts.read': true },
+        }
+        return roles[role] ?? {}
+      }
+
+      const can = createPermissions(fromRole('editor'))
+
+      expect(can('posts.read')).toBe(true)
+      expect(can('posts.create')).toBe(true)
+      expect(can('posts.delete')).toBe(false)
+      expect(can('users.read')).toBe(true)
+      expect(can('users.manage')).toBe(false)
+      expect(can('billing.view')).toBe(false)
+
+      // Promote to admin
+      can.set(fromRole('admin'))
+      expect(can('posts.delete')).toBe(true)
+      expect(can('users.manage')).toBe(true)
+      expect(can('billing.view')).toBe(true)
+    })
+
+    it('feature flags mixed with permissions', () => {
+      const can = createPermissions({
+        'posts.read': true,
+        'posts.create': true,
+        'feature.new-editor': true,
+        'feature.dark-mode': false,
+        'tier.pro': true,
+        'tier.enterprise': false,
+      })
+
+      expect(can('feature.new-editor')).toBe(true)
+      expect(can('feature.dark-mode')).toBe(false)
+      expect(can('tier.pro')).toBe(true)
+      expect(can('tier.enterprise')).toBe(false)
+    })
+
+    it('instance-level ownership checks', () => {
+      const currentUserId = 'user-42'
+
+      const can = createPermissions({
+        'posts.read': true,
+        'posts.update': (post: any) => post?.authorId === currentUserId,
+        'posts.delete': (post: any) =>
+          post?.authorId === currentUserId && post?.status === 'draft',
+      })
+
+      const myPost = { authorId: 'user-42', status: 'draft' }
+      const otherPost = { authorId: 'user-99', status: 'draft' }
+      const publishedPost = { authorId: 'user-42', status: 'published' }
+
+      expect(can('posts.update', myPost)).toBe(true)
+      expect(can('posts.update', otherPost)).toBe(false)
+      expect(can('posts.delete', myPost)).toBe(true)
+      expect(can('posts.delete', publishedPost)).toBe(false)
+    })
+
+    it('multi-tenant with key prefixes', () => {
+      const can = createPermissions({
+        'org:acme.admin': true,
+        'ws:design.posts.*': true,
+        'ws:engineering.posts.read': true,
+      })
+
+      expect(can('org:acme.admin')).toBe(true)
+      expect(can('ws:design.posts.read')).toBe(true)
+      expect(can('ws:design.posts.delete')).toBe(true)
+      expect(can('ws:engineering.posts.read')).toBe(true)
+      expect(can('ws:engineering.posts.delete')).toBe(false)
+    })
+
+    it('server response transformation', () => {
+      // Simulated server response
+      const serverResponse = {
+        permissions: ['posts:read', 'posts:create', 'users:read'],
+      }
+
+      // Simple transform — not a framework feature, just a .map()
+      const perms = Object.fromEntries(
+        serverResponse.permissions.map((p) => [p.replace(':', '.'), true]),
+      )
+
+      const can = createPermissions(perms)
+      expect(can('posts.read')).toBe(true)
+      expect(can('posts.create')).toBe(true)
+      expect(can('users.read')).toBe(true)
+      expect(can('posts.delete')).toBe(false)
+    })
+
+    it('superadmin with global wildcard', () => {
+      const can = createPermissions({ '*': true })
+      expect(can('literally.anything')).toBe(true)
+      expect(can('posts.read')).toBe(true)
+      expect(can('admin.nuclear-launch')).toBe(true)
+    })
+
+    it('reactive role switching', () => {
+      function fromRole(role: string): Record<string, boolean> {
+        if (role === 'admin') return { '*': true }
+        if (role === 'editor') return { 'posts.*': true, 'users.read': true }
+        return { 'posts.read': true }
+      }
+
+      const can = createPermissions(fromRole('viewer'))
+      const results: boolean[] = []
+
+      effect(() => {
+        results.push(can('posts.create'))
+      })
+
+      expect(results).toEqual([false])
+
+      can.set(fromRole('editor'))
+      expect(results).toEqual([false, true])
+
+      can.set(fromRole('admin'))
+      expect(results).toEqual([false, true, true])
+
+      can.set(fromRole('viewer'))
+      expect(results).toEqual([false, true, true, false])
+    })
+  })
+})

package/src/types.ts

@@ -0,0 +1,122 @@
+import type { Computed } from '@pyreon/reactivity'
+
+// ─── Permission values ───────────────────────────────────────────────────────
+
+/**
+ * A permission predicate — receives optional context and returns a boolean.
+ * Used for instance-level checks (e.g., "can update THIS post?").
+ */
+export type PermissionPredicate<TContext = unknown> = (
+  context?: TContext,
+) => boolean
+
+/**
+ * A permission value is either a static boolean or a predicate function.
+ * - `true` / `false` — static grant or denial
+ * - `(context?) => boolean` — dynamic, evaluated per-check
+ */
+export type PermissionValue<TContext = unknown> =
+  | boolean
+  | PermissionPredicate<TContext>
+
+// ─── Permission map ──────────────────────────────────────────────────────────
+
+/**
+ * A map of permission keys to their values.
+ * Keys are dot-separated strings (e.g., 'posts.read', 'users.manage').
+ * Wildcards are supported: 'posts.*' matches any 'posts.X' key.
+ */
+export type PermissionMap = Record<string, PermissionValue>
+
+// ─── Permissions instance ────────────────────────────────────────────────────
+
+/**
+ * The permissions instance returned by `createPermissions()`.
+ * Callable — `can('posts.read')` returns a boolean, reactive in effects/computeds/JSX.
+ */
+export interface Permissions {
+  /**
+   * Check if a permission is granted.
+   * Returns a boolean — reactive when read inside effects, computeds, or JSX `{() => ...}`.
+   *
+   * @param key - Permission key (e.g., 'posts.read')
+   * @param context - Optional context for predicate evaluation (e.g., a post instance)
+   *
+   * @example
+   * ```tsx
+   * can('posts.read')              // static check
+   * can('posts.update', post)      // instance check
+   * {() => can('posts.delete') && <DeleteButton />}
+   * ```
+   */
+  (key: string, context?: unknown): boolean
+
+  /**
+   * Inverse check — returns true when the permission is denied.
+   *
+   * @example
+   * ```tsx
+   * can.not('billing.export')  // true if user cannot export
+   * ```
+   */
+  not: (key: string, context?: unknown) => boolean
+
+  /**
+   * Check if ALL listed permissions are granted.
+   *
+   * @example
+   * ```tsx
+   * can.all('posts.read', 'posts.create')
+   * ```
+   */
+  all: (...keys: string[]) => boolean
+
+  /**
+   * Check if ANY of the listed permissions is granted.
+   *
+   * @example
+   * ```tsx
+   * can.any('posts.update', 'posts.delete')
+   * ```
+   */
+  any: (...keys: string[]) => boolean
+
+  /**
+   * Replace all permissions. All reactive reads update automatically.
+   *
+   * @example
+   * ```tsx
+   * can.set({ 'posts.read': true, 'users.manage': false })
+   * ```
+   */
+  set: (permissions: PermissionMap) => void
+
+  /**
+   * Merge permissions into the current map.
+   * Existing keys are overwritten, new keys are added.
+   *
+   * @example
+   * ```tsx
+   * can.patch({ 'billing.export': true })
+   * ```
+   */
+  patch: (permissions: PermissionMap) => void
+
+  /**
+   * All currently granted permission keys (static true + predicates that exist).
+   * Reactive signal — updates when permissions change.
+   *
+   * @example
+   * ```tsx
+   * // For help dialogs or admin dashboards
+   * can.granted()  // ['posts.read', 'posts.create', 'users.manage']
+   * ```
+   */
+  granted: Computed<string[]>
+
+  /**
+   * All permission entries as [key, value] pairs.
+   * Reactive signal — updates when permissions change.
+   */
+  entries: Computed<[string, PermissionValue][]>
+}