@nebutra/permissions 0.1.0 → 0.1.2

package/README.md

@@ -1,4 +1,4 @@
-> **Status: Foundation** — CASL in-process evaluation supports deterministic role inheritance, ABAC conditions, and field-level rules. OpenFGA remains a stub, so this package is not yet production-ready for Zanzibar-style relationship authorization.
+> **Status: Foundation** — CASL in-process evaluation supports deterministic role inheritance, ABAC conditions, and field-level rules. OpenFGA support now uses the store-scoped REST API, but model and tuple lifecycle management remain external to this package.
 
 # @nebutra/permissions
 
@@ -7,7 +7,7 @@ RBAC (Role-Based Access Control) and ABAC (Attribute-Based Access Control) permi
 ## Features
 
 - **CASL-based in-process evaluation** — Fast, no network calls, great for UI + API middleware
-- **OpenFGA integration** — Placeholder for managed/self-hosted Zanzibar relationship graphs
+- **OpenFGA integration** — Store-scoped REST checks, writes, deletes, and list-objects calls for managed/self-hosted Zanzibar relationship graphs
 - **Role hierarchy** — Roles inherit permissions from parent roles; child rules override inherited grants deterministically
 - **ABAC conditions** — Dynamic field resolution at evaluation time
 - **Field-level permissions** — Restrict access to specific fields through CASL-backed checks
@@ -186,13 +186,17 @@ const provider = createCASLProvider();
 
 ### OpenFGA (Relationship-Based)
 
-OpenFGA is still a foundation stub and should not be used for production relationship authorization yet.
+OpenFGA uses the store-scoped REST API and fails closed when configuration or network calls are invalid. This package does not manage OpenFGA authorization models or tuple migrations.
 
 ```typescript
 import { createOpenFGAProvider } from "@nebutra/permissions/openfga";
 
 const provider = createOpenFGAProvider(
-  "http://openfga.internal:8080",
+  {
+    apiUrl: "http://openfga.internal:8080",
+    storeId: "store_abc123",
+    authToken: process.env.OPENFGA_AUTH_TOKEN,
+  },
   roles
 );
 
@@ -220,7 +224,7 @@ PERMISSIONS_PROVIDER=casl              # "casl" | "openfga"
 
 # OpenFGA configuration
 OPENFGA_API_URL=http://openfga:8080    # Triggers OpenFGA provider
-OPENFGA_STORE_ID=abc123                # Optional
+OPENFGA_STORE_ID=abc123                # Required for OpenFGA REST calls
 OPENFGA_AUTH_TOKEN=secret              # Optional for managed OpenFGA
 ```
 
@@ -232,9 +236,11 @@ Initialize the global permissions manager (singleton).
 
 ```typescript
 const permissions = createPermissions({
-  provider: "casl",
+  provider: "openfga",
   roles: customRoles,
   openFgaApiUrl: "http://openfga:8080",
+  openFgaStoreId: "abc123",
+  openFgaAuthToken: process.env.OPENFGA_AUTH_TOKEN,
 });
 ```
 

package/dist/factory.d.ts

@@ -0,0 +1,18 @@
+import type { Action, PermissionConfig, PermissionContext, PermissionProvider, PermissionProviderType, PermissionRule, Resource, RoleDefinition } from "./types";
+export declare class PermissionsManager {
+    private provider;
+    private providerType;
+    constructor(config?: PermissionConfig);
+    private detectProvider;
+    getProviderType(): PermissionProviderType;
+    can(context: PermissionContext, action: Action, resource: Resource, subject?: unknown, field?: string): boolean;
+    cannot(context: PermissionContext, action: Action, resource: Resource, subject?: unknown, field?: string): boolean;
+    getRulesForRole(role: string): PermissionRule[];
+    defineRole(definition: RoleDefinition): void;
+    buildAbilityFor(context: PermissionContext): unknown;
+    getProvider(): PermissionProvider;
+}
+export declare function createPermissions(config?: PermissionConfig): PermissionsManager;
+export declare function getPermissions(): PermissionsManager;
+export declare function resetPermissions(): void;
+//# sourceMappingURL=factory.d.ts.map

package/dist/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../src/factory.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,MAAM,EACN,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,sBAAsB,EACtB,cAAc,EACd,QAAQ,EACR,cAAc,EACf,MAAM,SAAS,CAAC;AAIjB,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAqB;IACrC,OAAO,CAAC,YAAY,CAAyB;gBAEjC,MAAM,CAAC,EAAE,gBAAgB;IAyBrC,OAAO,CAAC,cAAc;IAmBtB,eAAe,IAAI,sBAAsB;IAIzC,GAAG,CACD,OAAO,EAAE,iBAAiB,EAC1B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE,OAAO,EACjB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO;IAIV,MAAM,CACJ,OAAO,EAAE,iBAAiB,EAC1B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE,OAAO,EACjB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO;IAIV,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,EAAE;IAI/C,UAAU,CAAC,UAAU,EAAE,cAAc,GAAG,IAAI;IAI5C,eAAe,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO;IAIpD,WAAW,IAAI,kBAAkB;CAGlC;AAED,wBAAgB,iBAAiB,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,kBAAkB,CAG/E;AAED,wBAAgB,cAAc,IAAI,kBAAkB,CAKnD;AAED,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC"}

package/dist/factory.js

@@ -0,0 +1,80 @@
+import { logger } from "@nebutra/logger";
+import { CASLProvider } from "./providers/casl";
+import { OpenFGAProvider } from "./providers/openfga";
+import { getDefaultRoles } from "./roles";
+let permissionsInstance = null;
+export class PermissionsManager {
+    provider;
+    providerType;
+    constructor(config) {
+        const detectedType = this.detectProvider(config?.provider);
+        this.providerType = detectedType;
+        const roles = config?.roles || getDefaultRoles();
+        if (detectedType === "openfga") {
+            // exactOptionalPropertyTypes: only set keys that have defined values so
+            // the optional `?:` modifier on OpenFGAProviderConfig stays satisfied.
+            const openFgaConfig = {};
+            if (config?.openFgaApiUrl !== undefined)
+                openFgaConfig.apiUrl = config.openFgaApiUrl;
+            if (config?.openFgaAuthToken !== undefined)
+                openFgaConfig.authToken = config.openFgaAuthToken;
+            if (config?.openFgaStoreId !== undefined)
+                openFgaConfig.storeId = config.openFgaStoreId;
+            this.provider = new OpenFGAProvider(openFgaConfig, roles);
+            logger.info("Initialized OpenFGA permissions provider");
+        }
+        else {
+            this.provider = new CASLProvider(roles);
+            logger.info("Initialized CASL permissions provider");
+        }
+    }
+    detectProvider(explicit) {
+        if (explicit) {
+            return explicit;
+        }
+        if (process.env.PERMISSIONS_PROVIDER) {
+            const provider = process.env.PERMISSIONS_PROVIDER;
+            if (["casl", "openfga"].includes(provider)) {
+                return provider;
+            }
+        }
+        if (process.env.OPENFGA_API_URL) {
+            return "openfga";
+        }
+        return "casl";
+    }
+    getProviderType() {
+        return this.providerType;
+    }
+    can(context, action, resource, subject, field) {
+        return this.provider.can(context, action, resource, subject, field);
+    }
+    cannot(context, action, resource, subject, field) {
+        return this.provider.cannot(context, action, resource, subject, field);
+    }
+    getRulesForRole(role) {
+        return this.provider.getRulesForRole(role);
+    }
+    defineRole(definition) {
+        this.provider.defineRole(definition);
+    }
+    buildAbilityFor(context) {
+        return this.provider.buildAbilityFor(context);
+    }
+    getProvider() {
+        return this.provider;
+    }
+}
+export function createPermissions(config) {
+    permissionsInstance = new PermissionsManager(config);
+    return permissionsInstance;
+}
+export function getPermissions() {
+    if (!permissionsInstance) {
+        permissionsInstance = new PermissionsManager();
+    }
+    return permissionsInstance;
+}
+export function resetPermissions() {
+    permissionsInstance = null;
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { createPermissions, getPermissions, PermissionsManager, resetPermissions, } from "./factory";
+export { attachPermissionContext, type RequirePermissionOptions, requirePermission, } from "./middleware";
+export { buildAbilityFor, CASLProvider, createCASLProvider, createPrismaAbility, getPrismaQuery, } from "./providers/casl";
+export { createOpenFGAProvider, type OpenFGACheckRequest, type OpenFGACheckResponse, type OpenFGAListObjectsRequest, OpenFGAProvider, type OpenFGAProviderConfig, type OpenFGATuple, type OpenFGAWriteRequest, } from "./providers/openfga";
+export { Can, Cannot, type CannotProps, type CanProps, PermissionProvider as PermissionProviderComponent, type PermissionProviderProps, type UsePermissionOptions, usePermission, usePermissionContext, } from "./react";
+export { DEFAULT_ROLES, getDefaultRoles, getRoleDefinition, getRoleHierarchy, } from "./roles";
+export { type AbilityOptions, type Action, ForbiddenError, type PermissionConfig, type PermissionContext, type PermissionProvider, type PermissionProviderType, type PermissionRule, type Resource, type Role, type RoleDefinition, } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,uBAAuB,EACvB,KAAK,wBAAwB,EAC7B,iBAAiB,GAClB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,eAAe,EACf,YAAY,EACZ,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,qBAAqB,EACrB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC9B,eAAe,EACf,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EACjB,KAAK,mBAAmB,GACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,GAAG,EACH,MAAM,EACN,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,kBAAkB,IAAI,2BAA2B,EACjD,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,aAAa,EACb,oBAAoB,GACrB,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,MAAM,EACX,cAAc,EACd,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC3B,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,IAAI,EACT,KAAK,cAAc,GACpB,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export { createPermissions, getPermissions, PermissionsManager, resetPermissions, } from "./factory";
+export { attachPermissionContext, requirePermission, } from "./middleware";
+export { buildAbilityFor, CASLProvider, createCASLProvider, createPrismaAbility, getPrismaQuery, } from "./providers/casl";
+export { createOpenFGAProvider, OpenFGAProvider, } from "./providers/openfga";
+export { Can, Cannot, PermissionProvider as PermissionProviderComponent, usePermission, usePermissionContext, } from "./react";
+export { DEFAULT_ROLES, getDefaultRoles, getRoleDefinition, getRoleHierarchy, } from "./roles";
+export { ForbiddenError, } from "./types";

package/dist/middleware.d.ts

@@ -0,0 +1,12 @@
+import type { Context, Next } from "hono";
+import type { Action, PermissionContext, Resource } from "./types";
+import { ForbiddenError } from "./types";
+export interface RequirePermissionOptions {
+    onDenied?: (c: Context, error: ForbiddenError) => Response | Promise<Response>;
+    extractSubject?: (c: Context) => unknown;
+}
+export declare function requirePermission(action: Action, resource: Resource, options?: RequirePermissionOptions): (c: Context, next: Next) => Promise<void | Response>;
+export declare function attachPermissionContext(extractUser: (c: Context) => PermissionContext | Promise<PermissionContext>): (c: Context, next: Next) => Promise<void | (Response & import("hono").TypedResponse<{
+    error: string;
+}, 500, "json">)>;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE1C,OAAO,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAEzC,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,cAAc,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC/E,cAAc,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC;CAC1C;AAED,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE,wBAAwB,IAEpB,GAAG,OAAO,EAAE,MAAM,IAAI,8BAoCrC;AAED,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,IAE7D,GAAG,OAAO,EAAE,MAAM,IAAI;;kBAWrC"}

package/dist/middleware.js

@@ -0,0 +1,45 @@
+import { logger } from "@nebutra/logger";
+import { getPermissions } from "./factory";
+import { ForbiddenError } from "./types";
+export function requirePermission(action, resource, options) {
+    return async (c, next) => {
+        const permissionsManager = getPermissions();
+        const user = c.get("user");
+        if (!user) {
+            logger.warn("requirePermission: no user context found");
+            return c.json({ error: "Unauthorized" }, 401);
+        }
+        const subject = options?.extractSubject?.(c);
+        const canAccess = permissionsManager.can(user, action, resource, subject);
+        if (!canAccess) {
+            const error = new ForbiddenError(action, resource, user);
+            logger.info("Permission denied", {
+                userId: user.userId,
+                action,
+                resource,
+                subject,
+            });
+            if (options?.onDenied) {
+                return options.onDenied(c, error);
+            }
+            return c.json({
+                error: "Forbidden",
+                message: error.message,
+            }, 403);
+        }
+        return next();
+    };
+}
+export function attachPermissionContext(extractUser) {
+    return async (c, next) => {
+        try {
+            const user = await extractUser(c);
+            c.set("user", user);
+        }
+        catch (error) {
+            logger.error("Failed to extract user context", { error });
+            return c.json({ error: "Internal Server Error" }, 500);
+        }
+        return next();
+    };
+}

package/dist/providers/casl.d.ts

@@ -0,0 +1,28 @@
+import { type Ability } from "@casl/ability";
+import { type PrismaQuery } from "@casl/prisma";
+import type { Action, PermissionContext, PermissionProvider, PermissionRule, Resource, RoleDefinition } from "../types";
+type AppAbility = Ability<[Action, Resource]>;
+export declare class CASLProvider implements PermissionProvider {
+    private abilities;
+    private roleDefinitions;
+    constructor(roles?: RoleDefinition[]);
+    defineRole(definition: RoleDefinition): void;
+    getRulesForRole(role: string): PermissionRule[];
+    buildAbilityFor(context: PermissionContext): AppAbility;
+    can(context: PermissionContext, action: Action, resource: Resource, subject?: unknown, field?: string): boolean;
+    cannot(context: PermissionContext, action: Action, resource: Resource, subject?: unknown, field?: string): boolean;
+    private collectRulesForContext;
+    private applyRule;
+    private getRoleHierarchy;
+    private resolveConditions;
+    private resolvePath;
+    private resolveSubject;
+    private getCacheKey;
+    clearCache(): void;
+}
+export declare function createCASLProvider(roles?: RoleDefinition[]): CASLProvider;
+export declare function buildAbilityFor(context: PermissionContext, roles?: RoleDefinition[]): AppAbility;
+export declare function createPrismaAbility(context: PermissionContext, roles?: RoleDefinition[]): AppAbility;
+export declare function getPrismaQuery(ability: AppAbility, action: Action, resource: Resource): PrismaQuery;
+export {};
+//# sourceMappingURL=casl.d.ts.map

package/dist/providers/casl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"casl.d.ts","sourceRoot":"","sources":["../../src/providers/casl.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,OAAO,EAIb,MAAM,eAAe,CAAC;AACvB,OAAO,EAAgB,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAE9D,OAAO,KAAK,EACV,MAAM,EACN,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,QAAQ,EACR,cAAc,EACf,MAAM,UAAU,CAAC;AAElB,KAAK,UAAU,GAAG,OAAO,CAAC,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;AAE9C,qBAAa,YAAa,YAAW,kBAAkB;IACrD,OAAO,CAAC,SAAS,CAAsC;IACvD,OAAO,CAAC,eAAe,CAA0C;gBAErD,KAAK,CAAC,EAAE,cAAc,EAAE;IASpC,UAAU,CAAC,UAAU,EAAE,cAAc,GAAG,IAAI;IAK5C,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,EAAE;IAc/C,eAAe,CAAC,OAAO,EAAE,iBAAiB,GAAG,UAAU;IAmBvD,GAAG,CACD,OAAO,EAAE,iBAAiB,EAC1B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE,OAAO,EACjB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO;IAKV,MAAM,CACJ,OAAO,EAAE,iBAAiB,EAC1B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE,OAAO,EACjB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO;IAKV,OAAO,CAAC,sBAAsB;IAW9B,OAAO,CAAC,SAAS;IA8BjB,OAAO,CAAC,gBAAgB;IAuBxB,OAAO,CAAC,iBAAiB;IAkBzB,OAAO,CAAC,WAAW;IAenB,OAAO,CAAC,cAAc;IAWtB,OAAO,CAAC,WAAW;IAInB,UAAU,IAAI,IAAI;CAGnB;AAED,wBAAgB,kBAAkB,CAAC,KAAK,CAAC,EAAE,cAAc,EAAE,GAAG,YAAY,CAEzE;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,iBAAiB,EAAE,KAAK,CAAC,EAAE,cAAc,EAAE,GAAG,UAAU,CAGhG;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,iBAAiB,EAC1B,KAAK,CAAC,EAAE,cAAc,EAAE,GACvB,UAAU,CAEZ;AAED,wBAAgB,cAAc,CAC5B,OAAO,EAAE,UAAU,EACnB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,QAAQ,GACjB,WAAW,CAOb"}

package/dist/providers/casl.js

@@ -0,0 +1,152 @@
+import { AbilityBuilder, subject as caslSubject, createMongoAbility, } from "@casl/ability";
+import { accessibleBy } from "@casl/prisma";
+import { getDefaultRoles } from "../roles";
+export class CASLProvider {
+    abilities = new Map();
+    roleDefinitions = new Map();
+    constructor(roles) {
+        const defaultRoles = getDefaultRoles();
+        const allRoles = [...defaultRoles, ...(roles || [])];
+        for (const role of allRoles) {
+            this.roleDefinitions.set(role.role, role);
+        }
+    }
+    defineRole(definition) {
+        this.roleDefinitions.set(definition.role, definition);
+        this.clearCache();
+    }
+    getRulesForRole(role) {
+        const hierarchy = this.getRoleHierarchy(role);
+        const rules = [];
+        for (const roleInHierarchy of hierarchy) {
+            const definition = this.roleDefinitions.get(roleInHierarchy);
+            if (definition) {
+                rules.push(...definition.rules);
+            }
+        }
+        return rules;
+    }
+    buildAbilityFor(context) {
+        const cacheKey = this.getCacheKey(context);
+        const cached = this.abilities.get(cacheKey);
+        if (cached) {
+            return cached;
+        }
+        const builder = new AbilityBuilder(createMongoAbility);
+        const rules = this.collectRulesForContext(context);
+        for (const rule of rules) {
+            this.applyRule(builder, rule, context);
+        }
+        const ability = builder.build();
+        this.abilities.set(cacheKey, ability);
+        return ability;
+    }
+    can(context, action, resource, subject, field) {
+        const ability = this.buildAbilityFor(context);
+        return ability.can(action, this.resolveSubject(resource, subject), field);
+    }
+    cannot(context, action, resource, subject, field) {
+        const ability = this.buildAbilityFor(context);
+        return ability.cannot(action, this.resolveSubject(resource, subject), field);
+    }
+    collectRulesForContext(context) {
+        const rules = [];
+        for (const role of context.roles) {
+            const roleRules = this.getRulesForRole(role);
+            rules.push(...roleRules);
+        }
+        return rules;
+    }
+    applyRule(builder, rule, context) {
+        const { can, cannot } = builder;
+        const actions = Array.isArray(rule.action) ? rule.action : [rule.action];
+        const resources = Array.isArray(rule.resource) ? rule.resource : [rule.resource];
+        const conditions = rule.conditions
+            ? this.resolveConditions(rule.conditions, context)
+            : undefined;
+        const method = rule.inverted ? cannot : can;
+        for (const action of actions) {
+            for (const resource of resources) {
+                const args = [action, resource];
+                if (rule.fields) {
+                    args.push(rule.fields);
+                }
+                if (conditions) {
+                    args.push(conditions);
+                }
+                method.apply(builder, args);
+            }
+        }
+    }
+    getRoleHierarchy(role, visited = new Set()) {
+        if (visited.has(role)) {
+            return [];
+        }
+        visited.add(role);
+        const definition = this.roleDefinitions.get(role);
+        const inherits = definition?.inherits
+            ? Array.isArray(definition.inherits)
+                ? definition.inherits
+                : [definition.inherits]
+            : [];
+        const hierarchy = [];
+        for (const inherited of inherits) {
+            hierarchy.push(...this.getRoleHierarchy(inherited, visited));
+        }
+        hierarchy.push(role);
+        return [...new Set(hierarchy)];
+    }
+    resolveConditions(conditions, context) {
+        const resolved = {};
+        for (const [key, value] of Object.entries(conditions)) {
+            if (typeof value === "string" && value.startsWith("${") && value.endsWith("}")) {
+                const path = value.slice(2, -1);
+                resolved[key] = this.resolvePath(path, context);
+            }
+            else {
+                resolved[key] = value;
+            }
+        }
+        return resolved;
+    }
+    resolvePath(path, context) {
+        const parts = path.split(".");
+        let current = context;
+        for (const part of parts) {
+            if (typeof current === "object" && current !== null) {
+                current = current[part];
+            }
+            else {
+                return undefined;
+            }
+        }
+        return current;
+    }
+    resolveSubject(resource, subject) {
+        if (subject && typeof subject === "object") {
+            return caslSubject(resource, subject);
+        }
+        return resource;
+    }
+    getCacheKey(context) {
+        return `${context.userId}:${context.tenantId}:${[...context.roles].sort().join(",")}`;
+    }
+    clearCache() {
+        this.abilities.clear();
+    }
+}
+export function createCASLProvider(roles) {
+    return new CASLProvider(roles);
+}
+export function buildAbilityFor(context, roles) {
+    const provider = new CASLProvider(roles);
+    return provider.buildAbilityFor(context);
+}
+export function createPrismaAbility(context, roles) {
+    return buildAbilityFor(context, roles);
+}
+export function getPrismaQuery(ability, action, resource) {
+    const prismaAbility = ability;
+    const queryByResource = accessibleBy(prismaAbility, action);
+    return queryByResource[resource] || {};
+}

package/dist/providers/openfga.d.ts

@@ -0,0 +1,58 @@
+import type { Action, PermissionContext, PermissionProvider, PermissionRule, Resource, RoleDefinition } from "../types";
+export interface OpenFGATuple {
+    user: string;
+    relation: string;
+    object: string;
+}
+export interface OpenFGAProviderConfig {
+    apiUrl?: string | undefined;
+    storeId?: string | undefined;
+    authToken?: string | undefined;
+}
+export interface OpenFGACheckRequest {
+    tuple_key: {
+        user: string;
+        relation: string;
+        object: string;
+    };
+}
+export interface OpenFGACheckResponse {
+    allowed: boolean;
+}
+export interface OpenFGAWriteRequest {
+    writes?: {
+        tuple_keys: OpenFGATuple[];
+    };
+    deletes?: {
+        tuple_keys: OpenFGATuple[];
+    };
+}
+export interface OpenFGAListObjectsRequest {
+    user: string;
+    relation: string;
+    type: string;
+}
+export declare class OpenFGAProvider implements PermissionProvider {
+    private apiUrl;
+    private storeId;
+    private authToken;
+    private roleDefinitions;
+    constructor(config?: string | OpenFGAProviderConfig, roles?: RoleDefinition[]);
+    defineRole(definition: RoleDefinition): void;
+    getRulesForRole(role: string): PermissionRule[];
+    private endpoint;
+    private headers;
+    check(user: string, relation: string, object: string): Promise<boolean>;
+    write(tuples: OpenFGATuple[]): Promise<void>;
+    delete(tuples: OpenFGATuple[]): Promise<void>;
+    listObjects(user: string, relation: string, type: string): Promise<string[]>;
+    can(_context: PermissionContext, _action: Action, _resource: Resource, _subject?: unknown): boolean;
+    cannot(context: PermissionContext, action: Action, resource: Resource, subject?: unknown): boolean;
+    canAsync(context: PermissionContext, action: Action, resource: Resource, subject?: unknown): Promise<boolean>;
+    private formatUser;
+    private formatObject;
+    private extractSubjectId;
+    buildAbilityFor(_context: PermissionContext): unknown;
+}
+export declare function createOpenFGAProvider(config?: string | OpenFGAProviderConfig, roles?: RoleDefinition[]): OpenFGAProvider;
+//# sourceMappingURL=openfga.d.ts.map

package/dist/providers/openfga.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openfga.d.ts","sourceRoot":"","sources":["../../src/providers/openfga.ts"],"names":[],"mappings":"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"}

package/dist/providers/openfga.js

@@ -0,0 +1,212 @@
+import { logger } from "@nebutra/logger";
+export class OpenFGAProvider {
+    apiUrl;
+    storeId;
+    authToken;
+    roleDefinitions = new Map();
+    constructor(config, roles) {
+        const resolvedConfig = typeof config === "string" ? { apiUrl: config } : config;
+        this.apiUrl = resolvedConfig?.apiUrl || process.env.OPENFGA_API_URL || "http://localhost:8080";
+        const resolvedStoreId = resolvedConfig?.storeId || process.env.OPENFGA_STORE_ID;
+        if (resolvedStoreId !== undefined)
+            this.storeId = resolvedStoreId;
+        const resolvedAuthToken = resolvedConfig?.authToken || process.env.OPENFGA_AUTH_TOKEN;
+        if (resolvedAuthToken !== undefined)
+            this.authToken = resolvedAuthToken;
+        if (roles) {
+            for (const role of roles) {
+                this.roleDefinitions.set(role.role, role);
+            }
+        }
+    }
+    defineRole(definition) {
+        this.roleDefinitions.set(definition.role, definition);
+    }
+    getRulesForRole(role) {
+        const definition = this.roleDefinitions.get(role);
+        return definition?.rules || [];
+    }
+    endpoint(path) {
+        if (!this.storeId) {
+            logger.error("OpenFGA store id is required", { path });
+            return null;
+        }
+        const apiUrl = this.apiUrl.replace(/\/+$/, "");
+        const storeId = encodeURIComponent(this.storeId);
+        return `${apiUrl}/stores/${storeId}/${path}`;
+    }
+    headers() {
+        const headers = { "Content-Type": "application/json" };
+        if (this.authToken) {
+            headers.Authorization = `Bearer ${this.authToken}`;
+        }
+        return headers;
+    }
+    async check(user, relation, object) {
+        const request = {
+            tuple_key: {
+                object,
+                relation,
+                user,
+            },
+        };
+        const endpoint = this.endpoint("check");
+        if (!endpoint) {
+            return false;
+        }
+        try {
+            const response = await fetch(endpoint, {
+                method: "POST",
+                headers: this.headers(),
+                body: JSON.stringify(request),
+            });
+            if (!response.ok) {
+                logger.error("OpenFGA check failed", { status: response.status, user, relation, object });
+                return false;
+            }
+            const data = await response.json();
+            return data.allowed === true;
+        }
+        catch (error) {
+            logger.error("OpenFGA check error", { error, user, relation, object });
+            return false;
+        }
+    }
+    async write(tuples) {
+        const request = {
+            writes: {
+                tuple_keys: tuples,
+            },
+        };
+        const endpoint = this.endpoint("write");
+        if (!endpoint) {
+            throw new Error("OpenFGA write failed: missing store id");
+        }
+        try {
+            const response = await fetch(endpoint, {
+                method: "POST",
+                headers: this.headers(),
+                body: JSON.stringify(request),
+            });
+            if (!response.ok) {
+                logger.error("OpenFGA write failed", { status: response.status });
+                throw new Error(`OpenFGA write failed: ${response.statusText}`);
+            }
+        }
+        catch (error) {
+            logger.error("OpenFGA write error", { error });
+            throw error;
+        }
+    }
+    async delete(tuples) {
+        const request = {
+            deletes: {
+                tuple_keys: tuples,
+            },
+        };
+        const endpoint = this.endpoint("write");
+        if (!endpoint) {
+            throw new Error("OpenFGA delete failed: missing store id");
+        }
+        try {
+            const response = await fetch(endpoint, {
+                method: "POST",
+                headers: this.headers(),
+                body: JSON.stringify(request),
+            });
+            if (!response.ok) {
+                logger.error("OpenFGA delete failed", { status: response.status });
+                throw new Error(`OpenFGA delete failed: ${response.statusText}`);
+            }
+        }
+        catch (error) {
+            logger.error("OpenFGA delete error", { error });
+            throw error;
+        }
+    }
+    async listObjects(user, relation, type) {
+        const request = {
+            relation,
+            type,
+            user,
+        };
+        const endpoint = this.endpoint("list-objects");
+        if (!endpoint) {
+            return [];
+        }
+        try {
+            const response = await fetch(endpoint, {
+                method: "POST",
+                headers: this.headers(),
+                body: JSON.stringify(request),
+            });
+            if (!response.ok) {
+                logger.error("OpenFGA listObjects failed", { status: response.status });
+                return [];
+            }
+            const data = await response.json();
+            return data.objects || [];
+        }
+        catch (error) {
+            logger.error("OpenFGA listObjects error", { error });
+            return [];
+        }
+    }
+    can(_context, _action, _resource, _subject) {
+        logger.warn("OpenFGAProvider.can() is synchronous wrapper - use checkAsync() for actual checks");
+        return false;
+    }
+    cannot(context, action, resource, subject) {
+        return !this.can(context, action, resource, subject);
+    }
+    async canAsync(context, action, resource, subject) {
+        const user = this.formatUser(context.userId);
+        const object = this.formatObject(resource, subject);
+        if (!user || !object) {
+            return false;
+        }
+        return this.check(user, action, object);
+    }
+    formatUser(userId) {
+        const trimmed = userId.trim();
+        if (!trimmed) {
+            return null;
+        }
+        return trimmed.includes(":") ? trimmed : `user:${trimmed}`;
+    }
+    formatObject(resource, subject) {
+        const objectId = this.extractSubjectId(subject);
+        if (!objectId) {
+            return null;
+        }
+        if (objectId.includes(":")) {
+            return objectId;
+        }
+        const objectType = String(resource).trim();
+        if (!objectType) {
+            return null;
+        }
+        return `${objectType}:${objectId}`;
+    }
+    extractSubjectId(subject) {
+        if (typeof subject === "string") {
+            const trimmed = subject.trim();
+            return trimmed || null;
+        }
+        if (subject === null || typeof subject !== "object" || Array.isArray(subject)) {
+            return null;
+        }
+        const id = subject.id;
+        if (typeof id !== "string") {
+            return null;
+        }
+        const trimmed = id.trim();
+        return trimmed || null;
+    }
+    buildAbilityFor(_context) {
+        return this;
+    }
+}
+export function createOpenFGAProvider(config, roles) {
+    return new OpenFGAProvider(config, roles);
+}

package/dist/react.d.ts

@@ -0,0 +1,35 @@
+import type { ReactElement, ReactNode } from "react";
+import type { Action, PermissionProvider as IPermissionProvider, PermissionContext, Resource } from "./types";
+interface PermissionContextValue {
+    provider: IPermissionProvider;
+    context: PermissionContext;
+}
+export interface PermissionProviderProps {
+    children: ReactNode;
+    provider: IPermissionProvider;
+    context: PermissionContext;
+}
+export declare function PermissionProvider({ children, provider, context, }: PermissionProviderProps): ReactElement;
+export declare function usePermissionContext(): PermissionContextValue;
+export interface UsePermissionOptions {
+    fallback?: boolean;
+}
+export declare function usePermission(action: Action, resource: Resource, subject?: unknown): boolean;
+export interface CanProps {
+    action: Action;
+    resource: Resource;
+    subject?: unknown;
+    children: ReactNode;
+    fallback?: ReactNode;
+}
+export declare function Can({ action, resource, subject, children, fallback, }: CanProps): ReactElement | null;
+export interface CannotProps {
+    action: Action;
+    resource: Resource;
+    subject?: unknown;
+    children: ReactNode;
+    fallback?: ReactNode;
+}
+export declare function Cannot({ action, resource, subject, children, fallback, }: CannotProps): ReactElement | null;
+export {};
+//# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAErD,OAAO,KAAK,EACV,MAAM,EACN,kBAAkB,IAAI,mBAAmB,EACzC,iBAAiB,EACjB,QAAQ,EACT,MAAM,SAAS,CAAC;AAEjB,UAAU,sBAAsB;IAC9B,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,OAAO,EAAE,iBAAiB,CAAC;CAC5B;AAID,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,SAAS,CAAC;IACpB,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,OAAO,EAAE,iBAAiB,CAAC;CAC5B;AAED,wBAAgB,kBAAkB,CAAC,EACjC,QAAQ,EACR,QAAQ,EACR,OAAO,GACR,EAAE,uBAAuB,GAAG,YAAY,CAMxC;AAED,wBAAgB,oBAAoB,IAAI,sBAAsB,CAM7D;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAM5F;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,SAAS,CAAC;IACpB,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED,wBAAgB,GAAG,CAAC,EAClB,MAAM,EACN,QAAQ,EACR,OAAO,EACP,QAAQ,EACR,QAAQ,GACT,EAAE,QAAQ,GAAG,YAAY,GAAG,IAAI,CAQhC;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,SAAS,CAAC;IACpB,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED,wBAAgB,MAAM,CAAC,EACrB,MAAM,EACN,QAAQ,EACR,OAAO,EACP,QAAQ,EACR,QAAQ,GACT,EAAE,WAAW,GAAG,YAAY,GAAG,IAAI,CAQnC"}

package/dist/react.js

@@ -0,0 +1,35 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { createContext, useContext, useMemo } from "react";
+const PermissionContextReact = createContext(null);
+export function PermissionProvider({ children, provider, context, }) {
+    const value = useMemo(() => ({ provider, context }), [provider, context]);
+    return (_jsx(PermissionContextReact.Provider, { value: value, children: children }));
+}
+export function usePermissionContext() {
+    const context = useContext(PermissionContextReact);
+    if (!context) {
+        throw new Error("usePermissionContext must be used within a PermissionProvider");
+    }
+    return context;
+}
+export function usePermission(action, resource, subject) {
+    const { provider, context } = usePermissionContext();
+    return useMemo(() => {
+        return provider.can(context, action, resource, subject);
+    }, [provider, context, action, resource, subject]);
+}
+export function Can({ action, resource, subject, children, fallback, }) {
+    const allowed = usePermission(action, resource, subject);
+    if (!allowed) {
+        return fallback ? fallback : null;
+    }
+    return _jsx(_Fragment, { children: children });
+}
+export function Cannot({ action, resource, subject, children, fallback, }) {
+    const allowed = usePermission(action, resource, subject);
+    if (allowed) {
+        return fallback ? fallback : null;
+    }
+    return _jsx(_Fragment, { children: children });
+}

package/dist/roles.d.ts

@@ -0,0 +1,6 @@
+import type { RoleDefinition } from "./types";
+export declare const DEFAULT_ROLES: Record<string, RoleDefinition>;
+export declare function getDefaultRoles(): RoleDefinition[];
+export declare function getRoleDefinition(role: string): RoleDefinition | undefined;
+export declare function getRoleHierarchy(role: string): string[];
+//# sourceMappingURL=roles.d.ts.map

package/dist/roles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.d.ts","sourceRoot":"","sources":["../src/roles.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAiJxD,CAAC;AAEF,wBAAgB,eAAe,IAAI,cAAc,EAAE,CAElD;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAE1E;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAcvD"}

package/dist/roles.js

@@ -0,0 +1,160 @@
+export const DEFAULT_ROLES = {
+    owner: {
+        role: "owner",
+        description: "Full control over workspace and all resources",
+        rules: [
+            {
+                action: [
+                    "create",
+                    "read",
+                    "update",
+                    "delete",
+                    "manage",
+                    "invite",
+                    "publish",
+                    "export",
+                    "share",
+                ],
+                resource: [
+                    "Document",
+                    "Project",
+                    "Workspace",
+                    "User",
+                    "Billing",
+                    "ApiKey",
+                    "Team",
+                    "Invite",
+                    "Integration",
+                ],
+            },
+        ],
+    },
+    admin: {
+        role: "admin",
+        inherits: "owner",
+        description: "Administrative access except billing transfer and workspace deletion",
+        rules: [
+            {
+                action: [
+                    "create",
+                    "read",
+                    "update",
+                    "delete",
+                    "manage",
+                    "invite",
+                    "publish",
+                    "export",
+                    "share",
+                ],
+                resource: ["Document", "Project", "User", "ApiKey", "Team", "Invite", "Integration"],
+            },
+            {
+                action: ["read", "update"],
+                resource: "Billing",
+                conditions: { scope: "read-only" },
+            },
+            {
+                action: ["delete"],
+                resource: "Workspace",
+                inverted: true,
+                reason: "Admins cannot delete the workspace",
+            },
+        ],
+    },
+    member: {
+        role: "member",
+        inherits: "viewer",
+        description: "CRUD own resources, read shared resources",
+        rules: [
+            {
+                action: ["create", "read", "update", "delete"],
+                resource: ["Document", "Project"],
+                conditions: { createdBy: "${user.userId}" },
+            },
+            {
+                action: ["read", "update"],
+                resource: ["Document", "Project"],
+                conditions: { sharedWith: "${user.userId}" },
+            },
+            {
+                action: ["read"],
+                resource: ["User", "Team"],
+            },
+            {
+                action: ["create", "read"],
+                resource: "ApiKey",
+                conditions: { owner: "${user.userId}" },
+            },
+            {
+                action: ["update", "delete"],
+                resource: "ApiKey",
+                conditions: { owner: "${user.userId}" },
+            },
+            {
+                action: ["invite"],
+                resource: "User",
+            },
+        ],
+    },
+    viewer: {
+        role: "viewer",
+        description: "Read-only access to shared resources",
+        rules: [
+            {
+                action: ["read"],
+                resource: ["Document", "Project", "User", "Team"],
+                conditions: { visibility: "public" },
+            },
+            {
+                action: ["read"],
+                resource: ["Document", "Project"],
+                conditions: { sharedWith: "${user.userId}" },
+            },
+        ],
+    },
+    billing_admin: {
+        role: "billing_admin",
+        inherits: "viewer",
+        description: "Manage billing and subscription",
+        rules: [
+            {
+                action: ["create", "read", "update"],
+                resource: "Billing",
+            },
+            {
+                action: ["read"],
+                resource: "Workspace",
+            },
+        ],
+    },
+    guest: {
+        role: "guest",
+        description: "Limited read access to specific shared resources only",
+        rules: [
+            {
+                action: ["read"],
+                resource: ["Document", "Project"],
+                conditions: { sharedWith: "${user.userId}", guestAccess: true },
+            },
+        ],
+    },
+};
+export function getDefaultRoles() {
+    return Object.values(DEFAULT_ROLES);
+}
+export function getRoleDefinition(role) {
+    return DEFAULT_ROLES[role];
+}
+export function getRoleHierarchy(role) {
+    const hierarchy = [role];
+    const definition = getRoleDefinition(role);
+    if (definition?.inherits) {
+        const inherits = Array.isArray(definition.inherits)
+            ? definition.inherits
+            : [definition.inherits];
+        for (const inherited of inherits) {
+            hierarchy.push(...getRoleHierarchy(inherited));
+        }
+    }
+    return [...new Set(hierarchy)];
+}

package/dist/types.d.ts

@@ -0,0 +1,48 @@
+export type Action = "create" | "read" | "update" | "delete" | "manage" | "invite" | "publish" | "export" | "share" | string;
+export type Resource = "Document" | "Project" | "Workspace" | "User" | "Billing" | "ApiKey" | "Team" | "Invite" | "Integration" | string;
+export type Role = "owner" | "admin" | "member" | "viewer" | "billing_admin" | "guest" | string;
+export interface PermissionRule {
+    action: Action | Action[];
+    resource: Resource | Resource[];
+    conditions?: Record<string, unknown>;
+    inverted?: boolean;
+    reason?: string;
+    fields?: string[];
+}
+export interface RoleDefinition {
+    role: Role;
+    inherits?: Role | Role[];
+    rules: PermissionRule[];
+    description?: string;
+}
+export interface PermissionContext {
+    userId: string;
+    tenantId: string;
+    roles: Role[];
+    attributes?: Record<string, unknown>;
+}
+export interface PermissionProvider {
+    can(context: PermissionContext, action: Action, resource: Resource, subject?: unknown, field?: string): boolean;
+    cannot(context: PermissionContext, action: Action, resource: Resource, subject?: unknown, field?: string): boolean;
+    getRulesForRole(role: Role): PermissionRule[];
+    defineRole(definition: RoleDefinition): void;
+    buildAbilityFor(context: PermissionContext): unknown;
+}
+export type PermissionProviderType = "casl" | "openfga";
+export interface PermissionConfig {
+    provider?: PermissionProviderType;
+    roles?: RoleDefinition[];
+    openFgaApiUrl?: string;
+    openFgaStoreId?: string | undefined;
+    openFgaAuthToken?: string | undefined;
+}
+export interface AbilityOptions {
+    resolveAction?: boolean;
+}
+export declare class ForbiddenError extends Error {
+    action: Action;
+    resource: Resource;
+    context?: PermissionContext | undefined;
+    constructor(action: Action, resource: Resource, context?: PermissionContext | undefined);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,MAAM,GACd,QAAQ,GACR,MAAM,GACN,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,OAAO,GACP,MAAM,CAAC;AAEX,MAAM,MAAM,QAAQ,GAChB,UAAU,GACV,SAAS,GACT,WAAW,GACX,MAAM,GACN,SAAS,GACT,QAAQ,GACR,MAAM,GACN,QAAQ,GACR,aAAa,GACb,MAAM,CAAC;AAEX,MAAM,MAAM,IAAI,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,eAAe,GAAG,OAAO,GAAG,MAAM,CAAC;AAEhG,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC1B,QAAQ,EAAE,QAAQ,GAAG,QAAQ,EAAE,CAAC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,IAAI,CAAC;IACX,QAAQ,CAAC,EAAE,IAAI,GAAG,IAAI,EAAE,CAAC;IACzB,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,kBAAkB;IACjC,GAAG,CACD,OAAO,EAAE,iBAAiB,EAC1B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE,OAAO,EACjB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC;IACX,MAAM,CACJ,OAAO,EAAE,iBAAiB,EAC1B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE,OAAO,EACjB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC;IACX,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,cAAc,EAAE,CAAC;IAC9C,UAAU,CAAC,UAAU,EAAE,cAAc,GAAG,IAAI,CAAC;IAC7C,eAAe,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC;CACtD;AAED,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,SAAS,CAAC;AAExD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,sBAAsB,CAAC;IAClC,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC;AAED,MAAM,WAAW,cAAc;IAC7B,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,qBAAa,cAAe,SAAQ,KAAK;IAE9B,MAAM,EAAE,MAAM;IACd,QAAQ,EAAE,QAAQ;IAClB,OAAO,CAAC,EAAE,iBAAiB;gBAF3B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE,iBAAiB,YAAA;CAKrC"}

package/dist/types.js

@@ -0,0 +1,12 @@
+export class ForbiddenError extends Error {
+    action;
+    resource;
+    context;
+    constructor(action, resource, context) {
+        super(`Forbidden: cannot ${action} on ${resource}`);
+        this.action = action;
+        this.resource = resource;
+        this.context = context;
+        this.name = "ForbiddenError";
+    }
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@nebutra/permissions",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "private": false,
-  "license": "AGPL-3.0",
+  "license": "MIT",
   "type": "module",
   "nebutra": {
     "status": "foundation",
@@ -12,7 +12,7 @@
       "or OPENFGA_API_URL + OPENFGA_STORE_ID for Zanzibar-style"
     ],
     "gaps": [
-      "OpenFGA adapter is a stub"
+      "OpenFGA model and tuple lifecycle management remain external"
     ],
     "featureId": "permissions",
     "category": "iam",
@@ -54,7 +54,7 @@
     "@casl/ability": "^6.7.0",
     "@casl/prisma": "^1.5.1",
     "zod": "^4.3.6",
-    "@nebutra/logger": "0.1.0"
+    "@nebutra/logger": "0.1.1"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",