@x12i/xentra-permissions

Permission engine for Xentra. Evaluates whether an actor may perform an action in an account context using memberships, roles, access rules, and delegations.

Install

npm install @x12i/xentra-permissions

Usage

import { can, type PermissionContext } from "@x12i/xentra-permissions";
import type { PermissionCheckRequest } from "@x12i/xentra-types";

const request: PermissionCheckRequest = {
  actor: { type: "user", id: "user_1" },
  action: "agents.manage",
  resource: { resourceType: "agent", resourceId: "agent_1" },
  context: { accountId: "acc_1" },
};

const context: PermissionContext = {
  account,
  memberships,
  roles,
  accessRules: [],
  delegations,
};

const result = can(request, context);
// { allowed: true, reason: "allowed_by_role", metadata?: ... }

Evaluation order

1. Valid actor and active account
2. Active delegation to the actor for the action
3. Active membership (users and teams)
4. Deny rules, then allow rules
5. Role permission keys (* wildcard supported)
6. Human approval requirement (extensible hook)

Reason codes include allowed_by_delegation, allowed_by_role, denied_by_rule, no_membership, requires_human_approval, and missing_permission.

Related packages

• @x12i/xentra-core — delegation and account helpers
• @x12i/xentra-types — PermissionCheckRequest, PermissionCheckResult
• @x12i/xentra-api — POST /v1/accounts/:accountId/access/check

Development

npm run build -w @x12i/xentra-permissions
npm test -w @x12i/xentra-permissions

License

MIT