access-control-js 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aashish Rai
+
+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/README.md

@@ -0,0 +1,327 @@
+# Access Control JS
+
+A lightweight, type-safe access control library for TypeScript applications. Supports both server-side (stateless) and client-side (reactive) environments.
+
+## Installation
+
+```bash
+npm install access-control-js
+```
+
+## Features
+
+- **Type-Safe**: Fully typed resources and actions based on your configuration.
+- **Isomorphic**: Works on both server (Node.js/Next.js) and client (React/Vanilla JS).
+- **Reactive**: Built-in subscription store for UI updates.
+- **Flexible**: Supports Role-Based (RBAC) and Attribute-Based (ABAC) access control.
+
+## Recommended Folder Structure
+
+```
+@/lib/access-control/
+  resources.ts   ← your resource & action config
+  policy.ts      ← policy builder
+  factory.ts     ← access control instance (client or server)
+  index.ts       ← barrel export
+```
+
+---
+
+## Usage
+
+### Step 1 — Define Resources & Actions
+
+```typescript
+// @/lib/access-control/resources.ts
+export const config = {
+  posts: ['read', 'create', 'update', 'delete'],
+  comments: ['create', 'delete'],
+  admin: ['manage_users', 'view_logs'],
+} as const;
+
+export type AppConfig = typeof config;
+```
+
+---
+
+### Step 2 — Define Your Policy
+
+```typescript
+// @/lib/access-control/policy.ts
+import { definePolicy } from 'access-control-js';
+import { type AppConfig } from './resources';
+
+export const policy = definePolicy<AppConfig>()
+  .allow('posts', ['read', 'create'])
+  .deny('posts', ['delete'])
+  .allow('comments', ['*'])
+  .build();
+```
+
+#### Policy Builder API
+
+| Method | Signature | Description |
+|---|---|---|
+| `definePolicy` | `definePolicy<T>()` | Creates a new typed `PolicyBuilder` |
+| `.allow` | `.allow(resource, actions, contexts?)` | Adds an allow statement |
+| `.deny` | `.deny(resource, actions, contexts?)` | Adds a deny statement |
+| `.build` | `.build()` | Returns the final `TAccessControlPolicy<T>` array |
+
+---
+
+### Step 3 — Create the Factory
+
+Pick **one** depending on your environment.
+
+#### Client-Side (Vanilla JS / React)
+
+Use `createAccessControl` to create a reactive store that can be updated after login.
+
+```typescript
+// @/lib/access-control/factory.ts
+import { createAccessControl } from 'access-control-js';
+import { type AppConfig } from './resources';
+import { policy } from './policy';
+
+export const authStore = createAccessControl<AppConfig>(policy);
+```
+
+**Check permissions:**
+
+```typescript
+import { authStore } from '@/lib/access-control/factory';
+
+const { can } = authStore.getSnapshot();
+
+can('posts', 'create'); // true | false
+```
+
+**Update policy after login:**
+
+```typescript
+import { authStore } from '@/lib/access-control/factory';
+
+async function login() {
+  const user = await api.login();
+  authStore.updatePolicy(user.policy);
+}
+```
+
+**Subscribe to policy changes:**
+
+```typescript
+import { authStore } from '@/lib/access-control/factory';
+
+const updateUI = () => {
+  const { can } = authStore.getSnapshot();
+  const btn = document.getElementById('delete-btn');
+  btn.style.display = can('posts', 'delete') ? 'block' : 'none';
+};
+
+updateUI();
+authStore.subscribe(updateUI);
+
+// Later, when policy updates...
+authStore.updatePolicy(newPolicy); // UI updates automatically
+```
+
+#### `createAccessControl` Store API
+
+| Method | Signature | Description |
+|---|---|---|
+| `updatePolicy` | `updatePolicy(policy, defaultContext?, options?)` | Replaces the policy, optionally updating default context and loading state |
+| `setLoading` | `setLoading(boolean)` | Sets `isLoading` state and notifies subscribers |
+| `subscribe` | `subscribe(listener)` | Registers a change listener; returns an unsubscribe function |
+| `getSnapshot` | `getSnapshot()` | Returns a stable snapshot with `can`, `canAll`, `canAny`, `canThese`, `policy`, `isLoading` |
+
+---
+
+#### Server-Side (API Routes / Server Components)
+
+Use `getAccessControl` for stateless, per-request environments.
+
+```typescript
+// @/lib/access-control/factory.ts
+import { getAccessControl } from 'access-control-js';
+import { type AppConfig } from './resources';
+import { policy } from './policy';
+
+export const ac = getAccessControl<AppConfig>(policy);
+```
+
+**Use in an API route or Server Component:**
+
+```typescript
+import { ac } from '@/lib/access-control/factory';
+
+export async function POST(req: Request) {
+  if (!ac.can('posts', 'create')) {
+    return new Response('Forbidden', { status: 403 });
+  }
+
+  // perform action...
+}
+```
+
+#### `getAccessControl` API
+
+| Method | Signature | Description |
+|---|---|---|
+| `can` | `can(resource, action, context?)` | Returns `true` if the action is allowed |
+| `canAll` | `canAll(resource, actions[], context?)` | Returns `true` if **all** actions are allowed |
+| `canAny` | `canAny(resource, actions[], context?)` | Returns `true` if **any** action is allowed |
+| `canThese` | `canThese(checks[])` | Returns a `Record<action, boolean>` for each check |
+| `policy` | `policy` | The policy array the instance was created with |
+| `isLoading` | `isLoading` | Always `false` for stateless instances |
+
+---
+
+### Step 4 — Merging Policies
+
+Combine a local static policy with a remote one fetched from your backend.
+
+```typescript
+// @/lib/access-control/policy.ts
+import { definePolicy, mergePolicies, type TAccessControlPolicy } from 'access-control-js';
+import { type AppConfig } from './resources';
+
+// 1. Local base policy
+const basePolicy = definePolicy<AppConfig>()
+  .allow('posts', ['read'])
+  .build();
+
+// 2. Fetch remote policy (e.g., from DB or API)
+const remotePolicy: TAccessControlPolicy<AppConfig> = await api.getPolicy();
+
+// 3. Merge — last policy takes precedence on overlaps
+export const policy = mergePolicies(basePolicy, remotePolicy);
+```
+
+| Function | Signature | Description |
+|---|---|---|
+| `mergePolicies` | `mergePolicies(...policies)` | Flattens multiple policy arrays into one |
+
+---
+
+## Advanced
+
+### Default Context (ABAC)
+
+Pass a default context that is automatically merged into every permission check. Useful for multi-tenant apps.
+
+```typescript
+// Server-side
+const ac = getAccessControl(policy, { defaultContext: { churchId: '123' } });
+ac.can('posts', 'read');                     // uses { churchId: '123' }
+ac.can('posts', 'read', { role: 'admin' });  // uses { churchId: '123', role: 'admin' }
+
+// Client-side — set at creation
+const authStore = createAccessControl<AppConfig>(policy, { defaultContext: { churchId: '123' } });
+
+// Update context alongside policy
+authStore.updatePolicy(newPolicy, { churchId: '456' });
+```
+
+### Loading State (UI)
+
+```typescript
+const store = createAccessControl([]);
+
+store.setLoading(true);
+
+// In React
+const { isLoading, can } = useAccessControl();
+if (isLoading) return <Spinner />;
+
+// Update policy and turn off loading in one go
+store.updatePolicy(newPolicy, undefined, { isLoading: false });
+```
+
+### Conflict Resolution
+
+By default, any deny rule at the highest specificity blocks access (`denyWins`). You can change this:
+
+| Strategy | Description |
+|---|---|
+| `denyWins` (default) | Any deny rule at the highest specificity blocks access |
+| `firstWins` | The first matching rule in the policy array determines the result |
+| `lastWins` | The last matching rule in the policy array determines the result |
+
+```typescript
+const ac = getAccessControl(policy, { conflictResolution: 'lastWins' });
+```
+
+### `AccessControlOptions`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `defaultContext` | `Record<string, any>` | `undefined` | Merged into every `can()` call automatically |
+| `conflictResolution` | `'denyWins' \| 'firstWins' \| 'lastWins'` | `'denyWins'` | Strategy for resolving conflicting allow/deny rules |
+
+---
+
+## Usage with Frameworks
+
+The examples below assume `authStore` is already exported from `@/lib/access-control/factory.ts`.
+
+### React
+
+```typescript
+// @/lib/access-control/factory.ts (add to existing file)
+import { useSyncExternalStore } from 'react';
+
+export const useAccessControl = () =>
+  useSyncExternalStore(authStore.subscribe, authStore.getSnapshot);
+```
+
+```tsx
+import { useAccessControl } from '@/lib/access-control/factory';
+
+export const CreatePostButton = () => {
+  const { can, isLoading } = useAccessControl();
+
+  if (isLoading) return <Spinner />;
+  if (!can('posts', 'create')) return null;
+
+  return <button>Create Post</button>;
+};
+```
+
+---
+
+### Vue
+
+```typescript
+// composables/useAccessControl.ts
+import { shallowRef, onUnmounted } from 'vue';
+import { authStore } from '@/lib/access-control/factory';
+
+export const useAccessControl = () => {
+  const snapshot = shallowRef(authStore.getSnapshot());
+
+  const unsubscribe = authStore.subscribe(() => {
+    snapshot.value = authStore.getSnapshot();
+  });
+
+  onUnmounted(unsubscribe);
+
+  return snapshot;
+};
+```
+
+```vue
+<!-- CreatePostButton.vue -->
+<script setup lang="ts">
+import { useAccessControl } from '@/composables/useAccessControl';
+
+const ac = useAccessControl();
+</script>
+
+<template>
+  <span v-if="ac.isLoading">Loading...</span>
+  <button v-else-if="ac.can('posts', 'create')">Create Post</button>
+</template>
+```
+
+---
+

package/dist/index.d.mts

@@ -0,0 +1,147 @@
+/**
+ * Configuration object defining resources and their available actions.
+ * Keys are resource names, and values are arrays of action strings.
+ * Use `as const` to ensure literal types are preserved.
+ */
+type AccessControlConfig = Record<string, readonly string[]>;
+/**
+ * A single statement in an access control policy.
+ * Defines a permission for a specific resource and actions.
+ */
+type TAccessControlStatement<T extends AccessControlConfig> = {
+    [R in keyof T]: {
+        /** The resource this statement applies to. */
+        resource: R;
+        /** The actions allowed or denied. Can include '*' for all actions. */
+        actions: readonly (T[R][number] | "*" | "")[];
+        /** The effect of the statement: 'allow' grants access, 'deny' blocks it. */
+        effect: "allow" | "deny";
+        /** Optional contexts for Attribute-Based Access Control (ABAC). Access is granted if ANY context object matches (OR logic). */
+        contexts?: readonly Record<string, any>[];
+    };
+}[keyof T];
+/**
+ * An access control policy consisting of an array of statements.
+ */
+type TAccessControlPolicy<T extends AccessControlConfig> = readonly TAccessControlStatement<T>[];
+/**
+ * Strategy for resolving conflicting permissions (e.g., when one rule allows and another denies).
+ * - `denyWins`: (Default) If any matching rule denies, access is denied.
+ * - `firstWins`: The first matching rule in the policy array wins.
+ * - `lastWins`: The last matching rule in the policy array wins.
+ */
+type ConflictResolutionStrategy = "denyWins" | "firstWins" | "lastWins";
+interface AccessControlOptions {
+    /** Optional default context merged into all permission checks. */
+    defaultContext?: Record<string, any>;
+    /** Strategy for resolving conflicting permissions. Defaults to 'denyWins'. */
+    conflictResolution?: ConflictResolutionStrategy;
+}
+/**
+ * The core access control interface returned by getAccessControl.
+ * Contains the policy and helper functions for checking permissions.
+ */
+interface CoreAccessControlType<T extends AccessControlConfig> {
+    /** The current access control policy. */
+    policy: TAccessControlPolicy<T>;
+    /** Indicates if the policy is currently loading. */
+    isLoading: boolean;
+    /** Checks if a specific action on a resource is allowed. */
+    can: <R extends keyof T>(resource: R, action: T[R][number], context?: Record<string, any> | Record<string, any>[]) => boolean;
+    /** Checks if ALL specified actions on a resource are allowed. */
+    canAll: <R extends keyof T>(resource: R, actions: T[R][number][], context?: Record<string, any> | Record<string, any>[]) => boolean;
+    /** Checks if ANY of the specified actions on a resource are allowed. */
+    canAny: <R extends keyof T>(resource: R, actions: T[R][number][], context?: Record<string, any> | Record<string, any>[]) => boolean;
+    /** Checks multiple actions on a resource at once. Returns an object mapping each action to its allow/deny status. */
+    canThese: <R extends keyof T>(resource: R, actions: T[R][number][], context?: Record<string, any> | Record<string, any>[]) => Record<T[R][number], boolean>;
+}
+/**
+ * The store interface returned by createAccessControl.
+ * Provides state management and a snapshot with all check methods.
+ */
+interface AccessControlStore<T extends AccessControlConfig> {
+    /** Updates the current policy and optionally the default context, then notifies listeners. */
+    updatePolicy: (newPolicy: TAccessControlPolicy<T>, defaultContext?: Record<string, any>, options?: {
+        isLoading?: boolean;
+    }) => void;
+    /** Manually sets the loading state and notifies listeners. */
+    setLoading: (isLoading: boolean) => void;
+    /** Subscribes to policy changes. Returns a cleanup function. */
+    subscribe: (listener: () => void) => () => void;
+    /** Returns a cached snapshot of the current access control state with all check methods. */
+    getSnapshot: () => CoreAccessControlType<T>;
+}
+
+/**
+ * Pure function to evaluate access against a specific policy state.
+ * This helper ensures logic is consistent across both static and dynamic implementations.
+ */
+declare const evaluateAccess: <T extends AccessControlConfig, R extends keyof T>(policy: TAccessControlPolicy<T>, resource: R, action: T[R][number], context?: Record<string, any> | Record<string, any>[], options?: AccessControlOptions) => boolean;
+/**
+ * Bulk version of evaluateAccess to check multiple actions on the same resource
+ * with the same context. Minimizes redundant policy filtering and context processing.
+ */
+declare const evaluateAccessBulk: <T extends AccessControlConfig, R extends keyof T>(policy: TAccessControlPolicy<T>, resource: R, actions: T[R][number][], context?: Record<string, any> | Record<string, any>[], options?: AccessControlOptions) => Record<T[R][number], boolean>;
+/**
+ * Creates a static access control interface.
+ * Ideal for server-side use (e.g., API routes, Server Components) where the policy is fixed per request.
+ *
+ * @param accessControlPolicy - The policy to evaluate.
+ * @param options - Optional configuration options (default context, conflict resolution).
+ * @returns An object containing `can`, `canAll`, and `canAny` functions.
+ */
+declare const getAccessControl: <T extends AccessControlConfig>(accessControlPolicy: TAccessControlPolicy<T>, optionsOrContext?: AccessControlOptions | Record<string, any>) => CoreAccessControlType<T>;
+/**
+ * Creates an updatable access control store with subscription capabilities.
+ * Ideal for client-side use where the policy may load asynchronously or change over time.
+ *
+ * @param initialPolicy - The initial policy to use.
+ * @param options - Optional configuration options (default context, conflict resolution).
+ * @returns An object containing policy updater, subscription method, and snapshot.
+ */
+declare const createAccessControl: <T extends AccessControlConfig>(initialPolicy: TAccessControlPolicy<T>, optionsOrContext?: AccessControlOptions | Record<string, any>) => AccessControlStore<T>;
+
+/**
+ * A fluent builder class to help create access control policies.
+ * Use `definePolicy()` to start a chain.
+ */
+declare class PolicyBuilder<T extends AccessControlConfig> {
+    private statements;
+    /**
+     * Allows one or more actions on a specific resource.
+     * @param resource The resource to grant access to.
+     * @param actions The actions to allow (or "*" for all).
+     * @param options Optional configuration, like ABAC contexts.
+     */
+    allow<R extends keyof T>(resource: R, actions: readonly (T[R][number] | "*" | "")[], options?: {
+        contexts?: readonly Record<string, any>[];
+    }): this;
+    /**
+     * Denies one or more actions on a specific resource.
+     * @param resource The resource to deny access to.
+     * @param actions The actions to deny (or "*" for all).
+     * @param options Optional configuration, like ABAC contexts.
+     */
+    deny<R extends keyof T>(resource: R, actions: readonly (T[R][number] | "*" | "")[], options?: {
+        contexts?: readonly Record<string, any>[];
+    }): this;
+    /**
+     * Returns the constructed policy as a plain array.
+     * This array is fully serializable and can be merged with other policies.
+     */
+    build(): TAccessControlPolicy<T>;
+}
+/**
+ * Helper to start building a policy using the fluent API.
+ * @returns A new PolicyBuilder instance.
+ */
+declare const definePolicy: <T extends AccessControlConfig>() => PolicyBuilder<T>;
+/**
+ * Merges multiple policy arrays into a single policy array.
+ * Useful for combining static policies with dynamic ones fetched from a backend.
+ * @param policies The list of policy arrays to merge.
+ * @returns A single flattened policy array.
+ */
+declare const mergePolicies: <T extends AccessControlConfig>(...policies: TAccessControlPolicy<T>[]) => TAccessControlPolicy<T>;
+
+export { type AccessControlConfig, type AccessControlOptions, type AccessControlStore, type ConflictResolutionStrategy, type CoreAccessControlType, PolicyBuilder, type TAccessControlPolicy, type TAccessControlStatement, createAccessControl, definePolicy, evaluateAccess, evaluateAccessBulk, getAccessControl, mergePolicies };

package/dist/index.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Configuration object defining resources and their available actions.
+ * Keys are resource names, and values are arrays of action strings.
+ * Use `as const` to ensure literal types are preserved.
+ */
+type AccessControlConfig = Record<string, readonly string[]>;
+/**
+ * A single statement in an access control policy.
+ * Defines a permission for a specific resource and actions.
+ */
+type TAccessControlStatement<T extends AccessControlConfig> = {
+    [R in keyof T]: {
+        /** The resource this statement applies to. */
+        resource: R;
+        /** The actions allowed or denied. Can include '*' for all actions. */
+        actions: readonly (T[R][number] | "*" | "")[];
+        /** The effect of the statement: 'allow' grants access, 'deny' blocks it. */
+        effect: "allow" | "deny";
+        /** Optional contexts for Attribute-Based Access Control (ABAC). Access is granted if ANY context object matches (OR logic). */
+        contexts?: readonly Record<string, any>[];
+    };
+}[keyof T];
+/**
+ * An access control policy consisting of an array of statements.
+ */
+type TAccessControlPolicy<T extends AccessControlConfig> = readonly TAccessControlStatement<T>[];
+/**
+ * Strategy for resolving conflicting permissions (e.g., when one rule allows and another denies).
+ * - `denyWins`: (Default) If any matching rule denies, access is denied.
+ * - `firstWins`: The first matching rule in the policy array wins.
+ * - `lastWins`: The last matching rule in the policy array wins.
+ */
+type ConflictResolutionStrategy = "denyWins" | "firstWins" | "lastWins";
+interface AccessControlOptions {
+    /** Optional default context merged into all permission checks. */
+    defaultContext?: Record<string, any>;
+    /** Strategy for resolving conflicting permissions. Defaults to 'denyWins'. */
+    conflictResolution?: ConflictResolutionStrategy;
+}
+/**
+ * The core access control interface returned by getAccessControl.
+ * Contains the policy and helper functions for checking permissions.
+ */
+interface CoreAccessControlType<T extends AccessControlConfig> {
+    /** The current access control policy. */
+    policy: TAccessControlPolicy<T>;
+    /** Indicates if the policy is currently loading. */
+    isLoading: boolean;
+    /** Checks if a specific action on a resource is allowed. */
+    can: <R extends keyof T>(resource: R, action: T[R][number], context?: Record<string, any> | Record<string, any>[]) => boolean;
+    /** Checks if ALL specified actions on a resource are allowed. */
+    canAll: <R extends keyof T>(resource: R, actions: T[R][number][], context?: Record<string, any> | Record<string, any>[]) => boolean;
+    /** Checks if ANY of the specified actions on a resource are allowed. */
+    canAny: <R extends keyof T>(resource: R, actions: T[R][number][], context?: Record<string, any> | Record<string, any>[]) => boolean;
+    /** Checks multiple actions on a resource at once. Returns an object mapping each action to its allow/deny status. */
+    canThese: <R extends keyof T>(resource: R, actions: T[R][number][], context?: Record<string, any> | Record<string, any>[]) => Record<T[R][number], boolean>;
+}
+/**
+ * The store interface returned by createAccessControl.
+ * Provides state management and a snapshot with all check methods.
+ */
+interface AccessControlStore<T extends AccessControlConfig> {
+    /** Updates the current policy and optionally the default context, then notifies listeners. */
+    updatePolicy: (newPolicy: TAccessControlPolicy<T>, defaultContext?: Record<string, any>, options?: {
+        isLoading?: boolean;
+    }) => void;
+    /** Manually sets the loading state and notifies listeners. */
+    setLoading: (isLoading: boolean) => void;
+    /** Subscribes to policy changes. Returns a cleanup function. */
+    subscribe: (listener: () => void) => () => void;
+    /** Returns a cached snapshot of the current access control state with all check methods. */
+    getSnapshot: () => CoreAccessControlType<T>;
+}
+
+/**
+ * Pure function to evaluate access against a specific policy state.
+ * This helper ensures logic is consistent across both static and dynamic implementations.
+ */
+declare const evaluateAccess: <T extends AccessControlConfig, R extends keyof T>(policy: TAccessControlPolicy<T>, resource: R, action: T[R][number], context?: Record<string, any> | Record<string, any>[], options?: AccessControlOptions) => boolean;
+/**
+ * Bulk version of evaluateAccess to check multiple actions on the same resource
+ * with the same context. Minimizes redundant policy filtering and context processing.
+ */
+declare const evaluateAccessBulk: <T extends AccessControlConfig, R extends keyof T>(policy: TAccessControlPolicy<T>, resource: R, actions: T[R][number][], context?: Record<string, any> | Record<string, any>[], options?: AccessControlOptions) => Record<T[R][number], boolean>;
+/**
+ * Creates a static access control interface.
+ * Ideal for server-side use (e.g., API routes, Server Components) where the policy is fixed per request.
+ *
+ * @param accessControlPolicy - The policy to evaluate.
+ * @param options - Optional configuration options (default context, conflict resolution).
+ * @returns An object containing `can`, `canAll`, and `canAny` functions.
+ */
+declare const getAccessControl: <T extends AccessControlConfig>(accessControlPolicy: TAccessControlPolicy<T>, optionsOrContext?: AccessControlOptions | Record<string, any>) => CoreAccessControlType<T>;
+/**
+ * Creates an updatable access control store with subscription capabilities.
+ * Ideal for client-side use where the policy may load asynchronously or change over time.
+ *
+ * @param initialPolicy - The initial policy to use.
+ * @param options - Optional configuration options (default context, conflict resolution).
+ * @returns An object containing policy updater, subscription method, and snapshot.
+ */
+declare const createAccessControl: <T extends AccessControlConfig>(initialPolicy: TAccessControlPolicy<T>, optionsOrContext?: AccessControlOptions | Record<string, any>) => AccessControlStore<T>;
+
+/**
+ * A fluent builder class to help create access control policies.
+ * Use `definePolicy()` to start a chain.
+ */
+declare class PolicyBuilder<T extends AccessControlConfig> {
+    private statements;
+    /**
+     * Allows one or more actions on a specific resource.
+     * @param resource The resource to grant access to.
+     * @param actions The actions to allow (or "*" for all).
+     * @param options Optional configuration, like ABAC contexts.
+     */
+    allow<R extends keyof T>(resource: R, actions: readonly (T[R][number] | "*" | "")[], options?: {
+        contexts?: readonly Record<string, any>[];
+    }): this;
+    /**
+     * Denies one or more actions on a specific resource.
+     * @param resource The resource to deny access to.
+     * @param actions The actions to deny (or "*" for all).
+     * @param options Optional configuration, like ABAC contexts.
+     */
+    deny<R extends keyof T>(resource: R, actions: readonly (T[R][number] | "*" | "")[], options?: {
+        contexts?: readonly Record<string, any>[];
+    }): this;
+    /**
+     * Returns the constructed policy as a plain array.
+     * This array is fully serializable and can be merged with other policies.
+     */
+    build(): TAccessControlPolicy<T>;
+}
+/**
+ * Helper to start building a policy using the fluent API.
+ * @returns A new PolicyBuilder instance.
+ */
+declare const definePolicy: <T extends AccessControlConfig>() => PolicyBuilder<T>;
+/**
+ * Merges multiple policy arrays into a single policy array.
+ * Useful for combining static policies with dynamic ones fetched from a backend.
+ * @param policies The list of policy arrays to merge.
+ * @returns A single flattened policy array.
+ */
+declare const mergePolicies: <T extends AccessControlConfig>(...policies: TAccessControlPolicy<T>[]) => TAccessControlPolicy<T>;
+
+export { type AccessControlConfig, type AccessControlOptions, type AccessControlStore, type ConflictResolutionStrategy, type CoreAccessControlType, PolicyBuilder, type TAccessControlPolicy, type TAccessControlStatement, createAccessControl, definePolicy, evaluateAccess, evaluateAccessBulk, getAccessControl, mergePolicies };

package/dist/index.js

@@ -0,0 +1,2 @@
+var m=Object.defineProperty;var S=Object.getOwnPropertyDescriptor;var w=Object.getOwnPropertyNames;var M=Object.prototype.hasOwnProperty;var L=(n,e)=>{for(var o in e)m(n,o,{get:e[o],enumerable:!0})},j=(n,e,o,s)=>{if(e&&typeof e=="object"||typeof e=="function")for(let t of w(e))!M.call(n,t)&&t!==o&&m(n,t,{get:()=>e[t],enumerable:!(s=S(e,t))||s.enumerable});return n};var K=n=>j(m({},"__esModule",{value:!0}),n);var E={};L(E,{PolicyBuilder:()=>A,createAccessControl:()=>$,definePolicy:()=>B,evaluateAccess:()=>k,evaluateAccessBulk:()=>x,getAccessControl:()=>W,mergePolicies:()=>D});module.exports=K(E);var p=(n,e,o)=>{let s=[],t=new Set;return n.forEach((r,f)=>{if(!(r.actions.includes("*")||r.actions.includes(e)))return;let l=r.contexts||[];if(l.length===0){s.push({effect:r.effect,specificity:0,index:f});return}if(o.length!==0)for(let i of l){let c=Object.keys(i),d=c.length,y=`${f}:${d}`;if(!t.has(y)){for(let g of o)if(c.every(u=>g[u]===i[u])){t.add(y),s.push({effect:r.effect,specificity:d,index:f});break}}}}),s},P=(n,e)=>{if(e==="firstWins")return n.sort((t,r)=>t.index-r.index),n[0].effect==="allow";if(e==="lastWins")return n.sort((t,r)=>r.index-t.index),n[0].effect==="allow";n.sort((t,r)=>r.specificity-t.specificity);let o=n[0].specificity;return!n.filter(t=>t.specificity===o).some(t=>t.effect==="deny")},k=(n,e,o,s,t)=>{let r=Array.isArray(s)?s:s?[s]:[],f=n.filter(l=>l.resource===e),a=p(f,o,r);return a.length===0?!1:P(a,(t==null?void 0:t.conflictResolution)??"denyWins")},x=(n,e,o,s,t)=>{let r={};if(o.length===0)return r;let f=Array.isArray(s)?s:s?[s]:[],a=n.filter(i=>i.resource===e);if(a.length===0){for(let i of o)r[i]=!1;return r}let l=(t==null?void 0:t.conflictResolution)??"denyWins";for(let i of o){let c=p(a,i,f);r[i]=c.length===0?!1:P(c,l)}return r},h=(n,e)=>n?e?Array.isArray(e)?e.map(o=>({...n,...o})):{...n,...e}:n:e,W=(n,e)=>{let o={};e&&("conflictResolution"in e||"defaultContext"in e?o=e:o={defaultContext:e});let{defaultContext:s}=o,t=(l,i,c)=>k(n,l,i,h(s,c),o),r=(l,i,c)=>{let d=a(l,i,c);return Object.values(d).every(y=>y===!0)},f=(l,i,c)=>{let d=a(l,i,c);return Object.values(d).some(y=>y===!0)},a=(l,i,c)=>x(n,l,i,h(s,c),o);return{policy:n,isLoading:!1,can:t,canAll:r,canAny:f,canThese:a}},$=(n,e)=>{let o={};e&&("conflictResolution"in e||"defaultContext"in e?o=e:o={defaultContext:e});let s=n,t=o.defaultContext,r=!1,f=new Set,a=(c,d,y)=>{let g=(u,R,T)=>x(c,u,R,h(d,T),o),C=(u,R,T)=>g(u,[R],T)[R];return{policy:c,isLoading:y??!1,can:C,canAll:(u,R,T)=>R.every(b=>C(u,b,T)),canAny:(u,R,T)=>{let b=g(u,R,T);return Object.values(b).some(v=>v===!0)},canThese:g}},l=a(s,t,r),i=()=>{for(let c of f)c()};return{updatePolicy:(c,d,y)=>{s=c,d!==void 0&&(t=d),(y==null?void 0:y.isLoading)!==void 0&&(r=y.isLoading),l=a(s,t,r),i()},setLoading:c=>{r!==c&&(r=c,l=a(s,t,r),i())},subscribe:c=>(f.add(c),()=>f.delete(c)),getSnapshot:()=>l}};var A=class{statements=[];allow(e,o,s){return this.statements=[...this.statements,{resource:e,actions:o,effect:"allow",contexts:s==null?void 0:s.contexts}],this}deny(e,o,s){return this.statements=[...this.statements,{resource:e,actions:o,effect:"deny",contexts:s==null?void 0:s.contexts}],this}build(){return[...this.statements]}},B=()=>new A,D=(...n)=>n.flat();0&&(module.exports={PolicyBuilder,createAccessControl,definePolicy,evaluateAccess,evaluateAccessBulk,getAccessControl,mergePolicies});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/core/policy.ts","../src/core/policy-builder.ts"],"sourcesContent":["export * from \"./core/index\";\n","import type {\n    AccessControlConfig,\n    AccessControlOptions,\n    AccessControlStore,\n    CoreAccessControlType,\n    TAccessControlPolicy,\n} from \"./types\";\n\ntype MatchedStatement = {\n    effect: \"allow\" | \"deny\";\n    specificity: number;\n    index: number;\n};\n\n/**\n * Collects matching statements for a single action against pre-filtered relevant statements.\n * Deduplicates by (index, specificity) — a statement can only contribute once per specificity\n * level regardless of how many context combinations match it.\n * Breaks early on the first input context that satisfies a policy condition.\n */\nconst collectMatchedStatements = <T extends AccessControlConfig>(\n    relevantStatements: TAccessControlPolicy<T>,\n    action: string,\n    // biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n    inputContexts: Record<string, any>[],\n): MatchedStatement[] => {\n    const matched: MatchedStatement[] = [];\n    const seen = new Set<string>();\n\n    relevantStatements.forEach((stmt, index) => {\n        // biome-ignore lint/suspicious/noExplicitAny: action is a string subtype\n        const actionMatches = stmt.actions.includes(\"*\") || stmt.actions.includes(action as any);\n        if (!actionMatches) return;\n\n        const policyConditions = stmt.contexts || [];\n\n        // No conditions — matches everything at specificity 0\n        if (policyConditions.length === 0) {\n            matched.push({ effect: stmt.effect, specificity: 0, index });\n            return;\n        }\n\n        if (inputContexts.length === 0) return;\n\n        // OR logic: any policy condition matching any input context is a match\n        for (const policyCondition of policyConditions) {\n            const conditionKeys = Object.keys(policyCondition);\n            const specificity = conditionKeys.length;\n            const dedupeKey = `${index}:${specificity}`;\n            if (seen.has(dedupeKey)) continue;\n\n            for (const inputContext of inputContexts) {\n                const allKeysMatch = conditionKeys.every(\n                    (k) => inputContext[k] === policyCondition[k],\n                );\n                if (allKeysMatch) {\n                    seen.add(dedupeKey);\n                    matched.push({ effect: stmt.effect, specificity, index });\n                    break; // No need to check further input contexts for this condition\n                }\n            }\n        }\n    });\n\n    return matched;\n};\n\n/**\n * Resolves a non-empty list of matched statements to allow/deny using the given strategy.\n */\nconst resolveConflict = (\n    matchedStatements: MatchedStatement[],\n    strategy: string,\n): boolean => {\n    if (strategy === \"firstWins\") {\n        matchedStatements.sort((a, b) => a.index - b.index);\n        return matchedStatements[0].effect === \"allow\";\n    }\n\n    if (strategy === \"lastWins\") {\n        matchedStatements.sort((a, b) => b.index - a.index);\n        return matchedStatements[0].effect === \"allow\";\n    }\n\n    // Default: \"denyWins\" — most specific statements take precedence; deny wins among ties\n    matchedStatements.sort((a, b) => b.specificity - a.specificity);\n    const maxSpecificity = matchedStatements[0].specificity;\n    const mostSpecific = matchedStatements.filter((s) => s.specificity === maxSpecificity);\n    return !mostSpecific.some((s) => s.effect === \"deny\");\n};\n\n/**\n * Pure function to evaluate access against a specific policy state.\n * This helper ensures logic is consistent across both static and dynamic implementations.\n */\nexport const evaluateAccess = <T extends AccessControlConfig, R extends keyof T>(\n    policy: TAccessControlPolicy<T>,\n    resource: R,\n    action: T[R][number],\n    // biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n    context?: Record<string, any> | Record<string, any>[],\n    options?: AccessControlOptions,\n): boolean => {\n    const inputContexts = Array.isArray(context) ? context : context ? [context] : [];\n    const relevantStatements = policy.filter((stmt) => stmt.resource === resource);\n    const matchedStatements = collectMatchedStatements(relevantStatements, action, inputContexts);\n\n    if (matchedStatements.length === 0) return false;\n\n    return resolveConflict(matchedStatements, options?.conflictResolution ?? \"denyWins\");\n};\n\n/**\n * Bulk version of evaluateAccess to check multiple actions on the same resource\n * with the same context. Minimizes redundant policy filtering and context processing.\n */\nexport const evaluateAccessBulk = <T extends AccessControlConfig, R extends keyof T>(\n    policy: TAccessControlPolicy<T>,\n    resource: R,\n    actions: T[R][number][],\n    // biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n    context?: Record<string, any> | Record<string, any>[],\n    options?: AccessControlOptions,\n): Record<T[R][number], boolean> => {\n    const results = {} as Record<T[R][number], boolean>;\n\n    if (actions.length === 0) return results;\n\n    // Normalize context and filter statements ONCE for all actions\n    const inputContexts = Array.isArray(context) ? context : context ? [context] : [];\n    const relevantStatements = policy.filter((stmt) => stmt.resource === resource);\n\n    if (relevantStatements.length === 0) {\n        for (const action of actions) results[action] = false;\n        return results;\n    }\n\n    const strategy = options?.conflictResolution ?? \"denyWins\";\n\n    for (const action of actions) {\n        const matchedStatements = collectMatchedStatements(relevantStatements, action, inputContexts);\n        results[action] = matchedStatements.length === 0\n            ? false\n            : resolveConflict(matchedStatements, strategy);\n    }\n\n    return results;\n};\n\n/**\n * Merges a default context into an explicit context.\n * Default context acts as a base — explicit context keys override default ones.\n */\nconst mergeContext = (\n    // biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n    defaultContext?: Record<string, any>,\n    // biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n    explicitContext?: Record<string, any> | Record<string, any>[],\n    // biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n): Record<string, any> | Record<string, any>[] | undefined => {\n    if (!defaultContext) return explicitContext;\n    if (!explicitContext) return defaultContext;\n    if (Array.isArray(explicitContext)) {\n        return explicitContext.map((c) => ({ ...defaultContext, ...c }));\n    }\n    return { ...defaultContext, ...explicitContext };\n};\n\n/**\n * Creates a static access control interface.\n * Ideal for server-side use (e.g., API routes, Server Components) where the policy is fixed per request.\n *\n * @param accessControlPolicy - The policy to evaluate.\n * @param options - Optional configuration options (default context, conflict resolution).\n * @returns An object containing `can`, `canAll`, and `canAny` functions.\n */\nexport const getAccessControl = <T extends AccessControlConfig>(\n    accessControlPolicy: TAccessControlPolicy<T>,\n    // biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n    optionsOrContext?: AccessControlOptions | Record<string, any>,\n): CoreAccessControlType<T> => {\n    // Backward compatibility: if second arg is a plain object without known option keys, treat as context\n    let options: AccessControlOptions = {};\n    if (optionsOrContext) {\n        if (\"conflictResolution\" in optionsOrContext || \"defaultContext\" in optionsOrContext) {\n            options = optionsOrContext as AccessControlOptions;\n        } else {\n            options = { defaultContext: optionsOrContext };\n        }\n    }\n\n    const { defaultContext } = options;\n\n    const can = <R extends keyof T>(\n        resource: R,\n        action: T[R][number],\n        // biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n        context?: Record<string, any> | Record<string, any>[],\n    ): boolean => {\n        return evaluateAccess(\n            accessControlPolicy,\n            resource,\n            action,\n            mergeContext(defaultContext, context),\n            options,\n        );\n    };\n\n    const canAll = <R extends keyof T>(\n        resource: R,\n        actions: T[R][number][],\n        // biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n        context?: Record<string, any> | Record<string, any>[],\n    ): boolean => {\n        const results = canThese(resource, actions, context);\n        return Object.values(results).every((v) => v === true);\n    };\n\n    const canAny = <R extends keyof T>(\n        resource: R,\n        actions: T[R][number][],\n        // biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n        context?: Record<string, any> | Record<string, any>[],\n    ): boolean => {\n        const results = canThese(resource, actions, context);\n        return Object.values(results).some((v) => v === true);\n    };\n\n    const canThese = <R extends keyof T>(\n        resource: R,\n        actions: T[R][number][],\n        // biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n        context?: Record<string, any> | Record<string, any>[],\n    ): Record<T[R][number], boolean> => {\n        return evaluateAccessBulk(\n            accessControlPolicy,\n            resource,\n            actions,\n            mergeContext(defaultContext, context),\n            options,\n        );\n    };\n\n    return {\n        policy: accessControlPolicy,\n        isLoading: false, // Static policies are never loading\n        can,\n        canAll,\n        canAny,\n        canThese,\n    };\n};\n\n/**\n * Creates an updatable access control store with subscription capabilities.\n * Ideal for client-side use where the policy may load asynchronously or change over time.\n *\n * @param initialPolicy - The initial policy to use.\n * @param options - Optional configuration options (default context, conflict resolution).\n * @returns An object containing policy updater, subscription method, and snapshot.\n */\nexport const createAccessControl = <T extends AccessControlConfig>(\n    initialPolicy: TAccessControlPolicy<T>,\n    // biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n    optionsOrContext?: AccessControlOptions | Record<string, any>,\n): AccessControlStore<T> => {\n     // Backward compatibility handling\n    let options: AccessControlOptions = {};\n    if (optionsOrContext) {\n        if (\"conflictResolution\" in optionsOrContext || \"defaultContext\" in optionsOrContext) {\n            options = optionsOrContext as AccessControlOptions;\n        } else {\n            options = { defaultContext: optionsOrContext };\n        }\n    }\n\n    let currentPolicy = initialPolicy;\n    let currentDefaultContext = options.defaultContext;\n    let currentIsLoading = false;\n    \n    const listeners = new Set<() => void>();\n\n    // Build a snapshot with all check methods bound to a specific policy.\n    // Cached and only rebuilt on updatePolicy/setLoading calls.\n    const buildSnapshot = (\n        policy: TAccessControlPolicy<T>,\n        // biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n            defCtx?: Record<string, any>,\n        loading?: boolean,\n    ): CoreAccessControlType<T> => {\n        const snapshotCanThese = <R extends keyof T>(\n            resource: R,\n            actions: T[R][number][],\n            // biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n            context?: Record<string, any> | Record<string, any>[],\n        ): Record<T[R][number], boolean> =>\n            evaluateAccessBulk(policy, resource, actions, mergeContext(defCtx, context), options);\n\n        const snapshotCan = <R extends keyof T>(\n            resource: R,\n            action: T[R][number],\n            // biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n            context?: Record<string, any> | Record<string, any>[],\n        ): boolean => snapshotCanThese(resource, [action], context)[action];\n\n        return {\n            policy,\n            isLoading: loading ?? false,\n            can: snapshotCan,\n            canAll: <R extends keyof T>(\n                resource: R,\n                actions: T[R][number][],\n                // biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n                context?: Record<string, any> | Record<string, any>[],\n            ): boolean => actions.every((a) => snapshotCan(resource, a, context)),\n            canAny: <R extends keyof T>(\n                resource: R,\n                actions: T[R][number][],\n                // biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n                context?: Record<string, any> | Record<string, any>[],\n            ): boolean => {\n                const results = snapshotCanThese(resource, actions, context);\n                return Object.values(results).some((a) => a === true);\n            },\n            canThese: snapshotCanThese,\n        };\n    };\n\n    let snapshot = buildSnapshot(currentPolicy, currentDefaultContext, currentIsLoading);\n\n    const notifyListeners = () => {\n        for (const listener of listeners) {\n            listener();\n        }\n    };\n\n    return {\n        updatePolicy: (\n            newPolicy: TAccessControlPolicy<T>,\n            // biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n            defaultContext?: Record<string, any>,\n            updateOptions?: { isLoading?: boolean }\n        ) => {\n            currentPolicy = newPolicy;\n            if (defaultContext !== undefined) {\n                currentDefaultContext = defaultContext;\n            }\n            if (updateOptions?.isLoading !== undefined) {\n                currentIsLoading = updateOptions.isLoading;\n            }\n            snapshot = buildSnapshot(currentPolicy, currentDefaultContext, currentIsLoading);\n            notifyListeners();\n        },\n        setLoading: (isLoading: boolean) => {\n            if (currentIsLoading === isLoading) return;\n            currentIsLoading = isLoading;\n            snapshot = buildSnapshot(currentPolicy, currentDefaultContext, currentIsLoading);\n            notifyListeners();\n        },\n        subscribe: (listener: () => void) => {\n            listeners.add(listener);\n            return () => listeners.delete(listener);\n        },\n        getSnapshot: () => snapshot,\n    };\n};","import type {\n\tAccessControlConfig,\n\tTAccessControlPolicy,\n} from \"./types\";\n\n/**\n * A fluent builder class to help create access control policies.\n * Use `definePolicy()` to start a chain.\n */\nexport class PolicyBuilder<T extends AccessControlConfig> {\n\tprivate statements: TAccessControlPolicy<T> = [];\n\n\t/**\n\t * Allows one or more actions on a specific resource.\n\t * @param resource The resource to grant access to.\n\t * @param actions The actions to allow (or \"*\" for all).\n\t * @param options Optional configuration, like ABAC contexts.\n\t */\n\tallow<R extends keyof T>(\n\t\tresource: R,\n\t\tactions: readonly (T[R][number] | \"*\" | \"\")[],\n\t\t// biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n\t\toptions?: { contexts?: readonly Record<string, any>[] },\n\t): this {\n\t\tthis.statements = [\n\t\t\t...this.statements,\n\t\t\t{\n\t\t\t\tresource,\n\t\t\t\tactions,\n\t\t\t\teffect: \"allow\",\n\t\t\t\tcontexts: options?.contexts,\n\t\t\t},\n\t\t] as unknown as TAccessControlPolicy<T>;\n\t\treturn this;\n\t}\n\n\t/**\n\t * Denies one or more actions on a specific resource.\n\t * @param resource The resource to deny access to.\n\t * @param actions The actions to deny (or \"*\" for all).\n\t * @param options Optional configuration, like ABAC contexts.\n\t */\n\tdeny<R extends keyof T>(\n\t\tresource: R,\n\t\tactions: readonly (T[R][number] | \"*\" | \"\")[],\n\t\t// biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n\t\toptions?: { contexts?: readonly Record<string, any>[] },\n\t): this {\n\t\tthis.statements = [\n\t\t\t...this.statements,\n\t\t\t{\n\t\t\t\tresource,\n\t\t\t\tactions,\n\t\t\t\teffect: \"deny\",\n\t\t\t\tcontexts: options?.contexts,\n\t\t\t},\n\t\t] as unknown as TAccessControlPolicy<T>;\n\t\treturn this;\n\t}\n\n\t/**\n\t * Returns the constructed policy as a plain array.\n\t * This array is fully serializable and can be merged with other policies.\n\t */\n\tbuild(): TAccessControlPolicy<T> {\n\t\treturn [...this.statements];\n\t}\n}\n\n/**\n * Helper to start building a policy using the fluent API.\n * @returns A new PolicyBuilder instance.\n */\nexport const definePolicy = <T extends AccessControlConfig>(): PolicyBuilder<T> => {\n\treturn new PolicyBuilder<T>();\n};\n\n/**\n * Merges multiple policy arrays into a single policy array.\n * Useful for combining static policies with dynamic ones fetched from a backend.\n * @param policies The list of policy arrays to merge.\n * @returns A single flattened policy array.\n */\nexport const mergePolicies = <T extends AccessControlConfig>(\n\t...policies: TAccessControlPolicy<T>[]\n): TAccessControlPolicy<T> => {\n\treturn policies.flat() as unknown as TAccessControlPolicy<T>;\n};\n"],"mappings":"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","names":["index_exports","__export","PolicyBuilder","createAccessControl","definePolicy","evaluateAccess","evaluateAccessBulk","getAccessControl","mergePolicies","__toCommonJS","collectMatchedStatements","relevantStatements","action","inputContexts","matched","seen","stmt","index","policyConditions","policyCondition","conditionKeys","specificity","dedupeKey","inputContext","k","resolveConflict","matchedStatements","strategy","a","b","maxSpecificity","s","evaluateAccess","policy","resource","context","options","evaluateAccessBulk","actions","results","mergeContext","defaultContext","explicitContext","c","getAccessControl","accessControlPolicy","optionsOrContext","can","canAll","canThese","v","canAny","createAccessControl","initialPolicy","currentPolicy","currentDefaultContext","currentIsLoading","listeners","buildSnapshot","defCtx","loading","snapshotCanThese","snapshotCan","snapshot","notifyListeners","listener","newPolicy","updateOptions","isLoading","PolicyBuilder","resource","actions","options","definePolicy","mergePolicies","policies"]}

package/dist/index.mjs

@@ -0,0 +1,2 @@
+var h=(t,e,o)=>{let n=[],r=new Set;return t.forEach((s,f)=>{if(!(s.actions.includes("*")||s.actions.includes(e)))return;let l=s.contexts||[];if(l.length===0){n.push({effect:s.effect,specificity:0,index:f});return}if(o.length!==0)for(let i of l){let c=Object.keys(i),d=c.length,y=`${f}:${d}`;if(!r.has(y)){for(let g of o)if(c.every(u=>g[u]===i[u])){r.add(y),n.push({effect:s.effect,specificity:d,index:f});break}}}}),n},x=(t,e)=>{if(e==="firstWins")return t.sort((r,s)=>r.index-s.index),t[0].effect==="allow";if(e==="lastWins")return t.sort((r,s)=>s.index-r.index),t[0].effect==="allow";t.sort((r,s)=>s.specificity-r.specificity);let o=t[0].specificity;return!t.filter(r=>r.specificity===o).some(r=>r.effect==="deny")},k=(t,e,o,n,r)=>{let s=Array.isArray(n)?n:n?[n]:[],f=t.filter(l=>l.resource===e),a=h(f,o,s);return a.length===0?!1:x(a,(r==null?void 0:r.conflictResolution)??"denyWins")},p=(t,e,o,n,r)=>{let s={};if(o.length===0)return s;let f=Array.isArray(n)?n:n?[n]:[],a=t.filter(i=>i.resource===e);if(a.length===0){for(let i of o)s[i]=!1;return s}let l=(r==null?void 0:r.conflictResolution)??"denyWins";for(let i of o){let c=h(a,i,f);s[i]=c.length===0?!1:x(c,l)}return s},b=(t,e)=>t?e?Array.isArray(e)?e.map(o=>({...t,...o})):{...t,...e}:t:e,v=(t,e)=>{let o={};e&&("conflictResolution"in e||"defaultContext"in e?o=e:o={defaultContext:e});let{defaultContext:n}=o,r=(l,i,c)=>k(t,l,i,b(n,c),o),s=(l,i,c)=>{let d=a(l,i,c);return Object.values(d).every(y=>y===!0)},f=(l,i,c)=>{let d=a(l,i,c);return Object.values(d).some(y=>y===!0)},a=(l,i,c)=>p(t,l,i,b(n,c),o);return{policy:t,isLoading:!1,can:r,canAll:s,canAny:f,canThese:a}},S=(t,e)=>{let o={};e&&("conflictResolution"in e||"defaultContext"in e?o=e:o={defaultContext:e});let n=t,r=o.defaultContext,s=!1,f=new Set,a=(c,d,y)=>{let g=(u,R,T)=>p(c,u,R,b(d,T),o),A=(u,R,T)=>g(u,[R],T)[R];return{policy:c,isLoading:y??!1,can:A,canAll:(u,R,T)=>R.every(C=>A(u,C,T)),canAny:(u,R,T)=>{let C=g(u,R,T);return Object.values(C).some(P=>P===!0)},canThese:g}},l=a(n,r,s),i=()=>{for(let c of f)c()};return{updatePolicy:(c,d,y)=>{n=c,d!==void 0&&(r=d),(y==null?void 0:y.isLoading)!==void 0&&(s=y.isLoading),l=a(n,r,s),i()},setLoading:c=>{s!==c&&(s=c,l=a(n,r,s),i())},subscribe:c=>(f.add(c),()=>f.delete(c)),getSnapshot:()=>l}};var m=class{statements=[];allow(e,o,n){return this.statements=[...this.statements,{resource:e,actions:o,effect:"allow",contexts:n==null?void 0:n.contexts}],this}deny(e,o,n){return this.statements=[...this.statements,{resource:e,actions:o,effect:"deny",contexts:n==null?void 0:n.contexts}],this}build(){return[...this.statements]}},M=()=>new m,L=(...t)=>t.flat();export{m as PolicyBuilder,S as createAccessControl,M as definePolicy,k as evaluateAccess,p as evaluateAccessBulk,v as getAccessControl,L as mergePolicies};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/policy.ts","../src/core/policy-builder.ts"],"sourcesContent":["import type {\n    AccessControlConfig,\n    AccessControlOptions,\n    AccessControlStore,\n    CoreAccessControlType,\n    TAccessControlPolicy,\n} from \"./types\";\n\ntype MatchedStatement = {\n    effect: \"allow\" | \"deny\";\n    specificity: number;\n    index: number;\n};\n\n/**\n * Collects matching statements for a single action against pre-filtered relevant statements.\n * Deduplicates by (index, specificity) — a statement can only contribute once per specificity\n * level regardless of how many context combinations match it.\n * Breaks early on the first input context that satisfies a policy condition.\n */\nconst collectMatchedStatements = <T extends AccessControlConfig>(\n    relevantStatements: TAccessControlPolicy<T>,\n    action: string,\n    // biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n    inputContexts: Record<string, any>[],\n): MatchedStatement[] => {\n    const matched: MatchedStatement[] = [];\n    const seen = new Set<string>();\n\n    relevantStatements.forEach((stmt, index) => {\n        // biome-ignore lint/suspicious/noExplicitAny: action is a string subtype\n        const actionMatches = stmt.actions.includes(\"*\") || stmt.actions.includes(action as any);\n        if (!actionMatches) return;\n\n        const policyConditions = stmt.contexts || [];\n\n        // No conditions — matches everything at specificity 0\n        if (policyConditions.length === 0) {\n            matched.push({ effect: stmt.effect, specificity: 0, index });\n            return;\n        }\n\n        if (inputContexts.length === 0) return;\n\n        // OR logic: any policy condition matching any input context is a match\n        for (const policyCondition of policyConditions) {\n            const conditionKeys = Object.keys(policyCondition);\n            const specificity = conditionKeys.length;\n            const dedupeKey = `${index}:${specificity}`;\n            if (seen.has(dedupeKey)) continue;\n\n            for (const inputContext of inputContexts) {\n                const allKeysMatch = conditionKeys.every(\n                    (k) => inputContext[k] === policyCondition[k],\n                );\n                if (allKeysMatch) {\n                    seen.add(dedupeKey);\n                    matched.push({ effect: stmt.effect, specificity, index });\n                    break; // No need to check further input contexts for this condition\n                }\n            }\n        }\n    });\n\n    return matched;\n};\n\n/**\n * Resolves a non-empty list of matched statements to allow/deny using the given strategy.\n */\nconst resolveConflict = (\n    matchedStatements: MatchedStatement[],\n    strategy: string,\n): boolean => {\n    if (strategy === \"firstWins\") {\n        matchedStatements.sort((a, b) => a.index - b.index);\n        return matchedStatements[0].effect === \"allow\";\n    }\n\n    if (strategy === \"lastWins\") {\n        matchedStatements.sort((a, b) => b.index - a.index);\n        return matchedStatements[0].effect === \"allow\";\n    }\n\n    // Default: \"denyWins\" — most specific statements take precedence; deny wins among ties\n    matchedStatements.sort((a, b) => b.specificity - a.specificity);\n    const maxSpecificity = matchedStatements[0].specificity;\n    const mostSpecific = matchedStatements.filter((s) => s.specificity === maxSpecificity);\n    return !mostSpecific.some((s) => s.effect === \"deny\");\n};\n\n/**\n * Pure function to evaluate access against a specific policy state.\n * This helper ensures logic is consistent across both static and dynamic implementations.\n */\nexport const evaluateAccess = <T extends AccessControlConfig, R extends keyof T>(\n    policy: TAccessControlPolicy<T>,\n    resource: R,\n    action: T[R][number],\n    // biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n    context?: Record<string, any> | Record<string, any>[],\n    options?: AccessControlOptions,\n): boolean => {\n    const inputContexts = Array.isArray(context) ? context : context ? [context] : [];\n    const relevantStatements = policy.filter((stmt) => stmt.resource === resource);\n    const matchedStatements = collectMatchedStatements(relevantStatements, action, inputContexts);\n\n    if (matchedStatements.length === 0) return false;\n\n    return resolveConflict(matchedStatements, options?.conflictResolution ?? \"denyWins\");\n};\n\n/**\n * Bulk version of evaluateAccess to check multiple actions on the same resource\n * with the same context. Minimizes redundant policy filtering and context processing.\n */\nexport const evaluateAccessBulk = <T extends AccessControlConfig, R extends keyof T>(\n    policy: TAccessControlPolicy<T>,\n    resource: R,\n    actions: T[R][number][],\n    // biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n    context?: Record<string, any> | Record<string, any>[],\n    options?: AccessControlOptions,\n): Record<T[R][number], boolean> => {\n    const results = {} as Record<T[R][number], boolean>;\n\n    if (actions.length === 0) return results;\n\n    // Normalize context and filter statements ONCE for all actions\n    const inputContexts = Array.isArray(context) ? context : context ? [context] : [];\n    const relevantStatements = policy.filter((stmt) => stmt.resource === resource);\n\n    if (relevantStatements.length === 0) {\n        for (const action of actions) results[action] = false;\n        return results;\n    }\n\n    const strategy = options?.conflictResolution ?? \"denyWins\";\n\n    for (const action of actions) {\n        const matchedStatements = collectMatchedStatements(relevantStatements, action, inputContexts);\n        results[action] = matchedStatements.length === 0\n            ? false\n            : resolveConflict(matchedStatements, strategy);\n    }\n\n    return results;\n};\n\n/**\n * Merges a default context into an explicit context.\n * Default context acts as a base — explicit context keys override default ones.\n */\nconst mergeContext = (\n    // biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n    defaultContext?: Record<string, any>,\n    // biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n    explicitContext?: Record<string, any> | Record<string, any>[],\n    // biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n): Record<string, any> | Record<string, any>[] | undefined => {\n    if (!defaultContext) return explicitContext;\n    if (!explicitContext) return defaultContext;\n    if (Array.isArray(explicitContext)) {\n        return explicitContext.map((c) => ({ ...defaultContext, ...c }));\n    }\n    return { ...defaultContext, ...explicitContext };\n};\n\n/**\n * Creates a static access control interface.\n * Ideal for server-side use (e.g., API routes, Server Components) where the policy is fixed per request.\n *\n * @param accessControlPolicy - The policy to evaluate.\n * @param options - Optional configuration options (default context, conflict resolution).\n * @returns An object containing `can`, `canAll`, and `canAny` functions.\n */\nexport const getAccessControl = <T extends AccessControlConfig>(\n    accessControlPolicy: TAccessControlPolicy<T>,\n    // biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n    optionsOrContext?: AccessControlOptions | Record<string, any>,\n): CoreAccessControlType<T> => {\n    // Backward compatibility: if second arg is a plain object without known option keys, treat as context\n    let options: AccessControlOptions = {};\n    if (optionsOrContext) {\n        if (\"conflictResolution\" in optionsOrContext || \"defaultContext\" in optionsOrContext) {\n            options = optionsOrContext as AccessControlOptions;\n        } else {\n            options = { defaultContext: optionsOrContext };\n        }\n    }\n\n    const { defaultContext } = options;\n\n    const can = <R extends keyof T>(\n        resource: R,\n        action: T[R][number],\n        // biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n        context?: Record<string, any> | Record<string, any>[],\n    ): boolean => {\n        return evaluateAccess(\n            accessControlPolicy,\n            resource,\n            action,\n            mergeContext(defaultContext, context),\n            options,\n        );\n    };\n\n    const canAll = <R extends keyof T>(\n        resource: R,\n        actions: T[R][number][],\n        // biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n        context?: Record<string, any> | Record<string, any>[],\n    ): boolean => {\n        const results = canThese(resource, actions, context);\n        return Object.values(results).every((v) => v === true);\n    };\n\n    const canAny = <R extends keyof T>(\n        resource: R,\n        actions: T[R][number][],\n        // biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n        context?: Record<string, any> | Record<string, any>[],\n    ): boolean => {\n        const results = canThese(resource, actions, context);\n        return Object.values(results).some((v) => v === true);\n    };\n\n    const canThese = <R extends keyof T>(\n        resource: R,\n        actions: T[R][number][],\n        // biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n        context?: Record<string, any> | Record<string, any>[],\n    ): Record<T[R][number], boolean> => {\n        return evaluateAccessBulk(\n            accessControlPolicy,\n            resource,\n            actions,\n            mergeContext(defaultContext, context),\n            options,\n        );\n    };\n\n    return {\n        policy: accessControlPolicy,\n        isLoading: false, // Static policies are never loading\n        can,\n        canAll,\n        canAny,\n        canThese,\n    };\n};\n\n/**\n * Creates an updatable access control store with subscription capabilities.\n * Ideal for client-side use where the policy may load asynchronously or change over time.\n *\n * @param initialPolicy - The initial policy to use.\n * @param options - Optional configuration options (default context, conflict resolution).\n * @returns An object containing policy updater, subscription method, and snapshot.\n */\nexport const createAccessControl = <T extends AccessControlConfig>(\n    initialPolicy: TAccessControlPolicy<T>,\n    // biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n    optionsOrContext?: AccessControlOptions | Record<string, any>,\n): AccessControlStore<T> => {\n     // Backward compatibility handling\n    let options: AccessControlOptions = {};\n    if (optionsOrContext) {\n        if (\"conflictResolution\" in optionsOrContext || \"defaultContext\" in optionsOrContext) {\n            options = optionsOrContext as AccessControlOptions;\n        } else {\n            options = { defaultContext: optionsOrContext };\n        }\n    }\n\n    let currentPolicy = initialPolicy;\n    let currentDefaultContext = options.defaultContext;\n    let currentIsLoading = false;\n    \n    const listeners = new Set<() => void>();\n\n    // Build a snapshot with all check methods bound to a specific policy.\n    // Cached and only rebuilt on updatePolicy/setLoading calls.\n    const buildSnapshot = (\n        policy: TAccessControlPolicy<T>,\n        // biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n            defCtx?: Record<string, any>,\n        loading?: boolean,\n    ): CoreAccessControlType<T> => {\n        const snapshotCanThese = <R extends keyof T>(\n            resource: R,\n            actions: T[R][number][],\n            // biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n            context?: Record<string, any> | Record<string, any>[],\n        ): Record<T[R][number], boolean> =>\n            evaluateAccessBulk(policy, resource, actions, mergeContext(defCtx, context), options);\n\n        const snapshotCan = <R extends keyof T>(\n            resource: R,\n            action: T[R][number],\n            // biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n            context?: Record<string, any> | Record<string, any>[],\n        ): boolean => snapshotCanThese(resource, [action], context)[action];\n\n        return {\n            policy,\n            isLoading: loading ?? false,\n            can: snapshotCan,\n            canAll: <R extends keyof T>(\n                resource: R,\n                actions: T[R][number][],\n                // biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n                context?: Record<string, any> | Record<string, any>[],\n            ): boolean => actions.every((a) => snapshotCan(resource, a, context)),\n            canAny: <R extends keyof T>(\n                resource: R,\n                actions: T[R][number][],\n                // biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n                context?: Record<string, any> | Record<string, any>[],\n            ): boolean => {\n                const results = snapshotCanThese(resource, actions, context);\n                return Object.values(results).some((a) => a === true);\n            },\n            canThese: snapshotCanThese,\n        };\n    };\n\n    let snapshot = buildSnapshot(currentPolicy, currentDefaultContext, currentIsLoading);\n\n    const notifyListeners = () => {\n        for (const listener of listeners) {\n            listener();\n        }\n    };\n\n    return {\n        updatePolicy: (\n            newPolicy: TAccessControlPolicy<T>,\n            // biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n            defaultContext?: Record<string, any>,\n            updateOptions?: { isLoading?: boolean }\n        ) => {\n            currentPolicy = newPolicy;\n            if (defaultContext !== undefined) {\n                currentDefaultContext = defaultContext;\n            }\n            if (updateOptions?.isLoading !== undefined) {\n                currentIsLoading = updateOptions.isLoading;\n            }\n            snapshot = buildSnapshot(currentPolicy, currentDefaultContext, currentIsLoading);\n            notifyListeners();\n        },\n        setLoading: (isLoading: boolean) => {\n            if (currentIsLoading === isLoading) return;\n            currentIsLoading = isLoading;\n            snapshot = buildSnapshot(currentPolicy, currentDefaultContext, currentIsLoading);\n            notifyListeners();\n        },\n        subscribe: (listener: () => void) => {\n            listeners.add(listener);\n            return () => listeners.delete(listener);\n        },\n        getSnapshot: () => snapshot,\n    };\n};","import type {\n\tAccessControlConfig,\n\tTAccessControlPolicy,\n} from \"./types\";\n\n/**\n * A fluent builder class to help create access control policies.\n * Use `definePolicy()` to start a chain.\n */\nexport class PolicyBuilder<T extends AccessControlConfig> {\n\tprivate statements: TAccessControlPolicy<T> = [];\n\n\t/**\n\t * Allows one or more actions on a specific resource.\n\t * @param resource The resource to grant access to.\n\t * @param actions The actions to allow (or \"*\" for all).\n\t * @param options Optional configuration, like ABAC contexts.\n\t */\n\tallow<R extends keyof T>(\n\t\tresource: R,\n\t\tactions: readonly (T[R][number] | \"*\" | \"\")[],\n\t\t// biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n\t\toptions?: { contexts?: readonly Record<string, any>[] },\n\t): this {\n\t\tthis.statements = [\n\t\t\t...this.statements,\n\t\t\t{\n\t\t\t\tresource,\n\t\t\t\tactions,\n\t\t\t\teffect: \"allow\",\n\t\t\t\tcontexts: options?.contexts,\n\t\t\t},\n\t\t] as unknown as TAccessControlPolicy<T>;\n\t\treturn this;\n\t}\n\n\t/**\n\t * Denies one or more actions on a specific resource.\n\t * @param resource The resource to deny access to.\n\t * @param actions The actions to deny (or \"*\" for all).\n\t * @param options Optional configuration, like ABAC contexts.\n\t */\n\tdeny<R extends keyof T>(\n\t\tresource: R,\n\t\tactions: readonly (T[R][number] | \"*\" | \"\")[],\n\t\t// biome-ignore lint/suspicious/noExplicitAny: Context can have any value type\n\t\toptions?: { contexts?: readonly Record<string, any>[] },\n\t): this {\n\t\tthis.statements = [\n\t\t\t...this.statements,\n\t\t\t{\n\t\t\t\tresource,\n\t\t\t\tactions,\n\t\t\t\teffect: \"deny\",\n\t\t\t\tcontexts: options?.contexts,\n\t\t\t},\n\t\t] as unknown as TAccessControlPolicy<T>;\n\t\treturn this;\n\t}\n\n\t/**\n\t * Returns the constructed policy as a plain array.\n\t * This array is fully serializable and can be merged with other policies.\n\t */\n\tbuild(): TAccessControlPolicy<T> {\n\t\treturn [...this.statements];\n\t}\n}\n\n/**\n * Helper to start building a policy using the fluent API.\n * @returns A new PolicyBuilder instance.\n */\nexport const definePolicy = <T extends AccessControlConfig>(): PolicyBuilder<T> => {\n\treturn new PolicyBuilder<T>();\n};\n\n/**\n * Merges multiple policy arrays into a single policy array.\n * Useful for combining static policies with dynamic ones fetched from a backend.\n * @param policies The list of policy arrays to merge.\n * @returns A single flattened policy array.\n */\nexport const mergePolicies = <T extends AccessControlConfig>(\n\t...policies: TAccessControlPolicy<T>[]\n): TAccessControlPolicy<T> => {\n\treturn policies.flat() as unknown as TAccessControlPolicy<T>;\n};\n"],"mappings":"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","names":["collectMatchedStatements","relevantStatements","action","inputContexts","matched","seen","stmt","index","policyConditions","policyCondition","conditionKeys","specificity","dedupeKey","inputContext","k","resolveConflict","matchedStatements","strategy","a","b","maxSpecificity","s","evaluateAccess","policy","resource","context","options","evaluateAccessBulk","actions","results","mergeContext","defaultContext","explicitContext","c","getAccessControl","accessControlPolicy","optionsOrContext","can","canAll","canThese","v","canAny","createAccessControl","initialPolicy","currentPolicy","currentDefaultContext","currentIsLoading","listeners","buildSnapshot","defCtx","loading","snapshotCanThese","snapshotCan","snapshot","notifyListeners","listener","newPolicy","updateOptions","isLoading","PolicyBuilder","resource","actions","options","definePolicy","mergePolicies","policies"]}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "access-control-js",
+  "version": "0.1.0",
+  "description": "A lightweight, type-safe access control library for TypeScript applications.",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest",
+    "lint": "biome check .",
+    "format": "biome check --apply .",
+    "prepublishOnly": "npm run build",
+    "prepare": "husky"
+  },
+  "keywords": [
+    "access-control",
+    "rbac",
+    "abac",
+    "authorization",
+    "typescript"
+  ],
+  "author": "Aashish Rai",
+  "license": "MIT",
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@commitlint/cli": "^20.5.0",
+    "@commitlint/config-conventional": "^20.5.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.4.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "lint-staged": {
+    "*.{ts,tsx,js,jsx,json}": "biome check --apply --no-errors-on-unmatched"
+  }
+}