@pleri/pylon-core

Substrate-agnostic authz primitives — Actor, Archetype, Capability, requireCapability, expandArchetype. Used internally by @pleri/pylon (SDK) and @pleri/pylon-cli; consumable by any MCP SDK or embedded authz layer that wants the same types without the Pylon runtime.

Install

pnpm add @pleri/pylon-core

Requires Node ≥ 22 (or any runtime with Web Crypto for hashEmail). ESM only.

What's in the box

import {
  type Actor,
  type Archetype,
  type Capability,
  type RoleEntry,
  type RoleStoreReader,
  requireCapability,
  hasCapability,
  expandArchetype,
  resolveActor,
  hashEmail,
  // error classes
  CapabilityDeniedError,
  UnresolvedActorError,
  UndeclaredRouteError,
  UnknownArchetypeError,
  ArchetypeCycleError,
} from '@pleri/pylon-core';

Everything is generic over a consumer-defined capability vocabulary (TCap extends string), so each MCP preserves compile-time safety on its own namespace (olam:world.read, pleri:billing.write, etc.).

Example

import { expandArchetype, requireCapability, type Archetype } from '@pleri/pylon-core';

type OlamCap = 'olam:world.read' | 'olam:world.write';

const archetypes: Archetype<OlamCap>[] = [
  { name: 'olam:user',  capabilities: ['olam:world.read'] },
  { name: 'olam:admin', capabilities: ['olam:world.write'], inherits: ['olam:user'] },
];

const caps = expandArchetype(archetypes, 'olam:admin');
// Set { 'olam:world.read', 'olam:world.write' }

const actor = {
  email: 'alice@co',
  archetype: 'olam:admin',
  capabilities: caps,
  isDefault: false,
};

requireCapability(actor, 'olam:world.write'); // returns; throws CapabilityDeniedError if missing

Invariant

Nothing in this package imports from anywhere else in the @pleri/* workspace. It's the shared vocabulary every Pylon consumer speaks.

License

MIT — see LICENSE.