Polizy Setup

Guide for installing and configuring polizy in your project.

When to Apply

User says "add authorization to my project"
User says "install polizy" or "set up polizy"
User has no existing polizy configuration
User asks about initial setup or storage selection
User is starting a new project with authorization needs

Priority Table

Priority	Task	Notes
Critical	Install package	`npm install polizy`
Critical	Define schema	Relations, actions, mappings
Critical	Choose storage	InMemory (dev) or Prisma (prod)
Important	Test setup	Verify with a permission check
Optional	Configure options	Depth limits, logging

Step-by-Step Setup

Step 1: Install

npm install polizy
# or
pnpm add polizy
# or
yarn add polizy

Step 2: Define Schema

Create your authorization model:

import { defineSchema } from "polizy";

const schema = defineSchema({
  // Define relationship types
  relations: {
    owner: { type: "direct" },    // Direct user → resource
    editor: { type: "direct" },
    viewer: { type: "direct" },
    member: { type: "group" },    // Group membership
    parent: { type: "hierarchy" } // Folder → file
  },

  // Map actions to relations that grant them
  actionToRelations: {
    delete: ["owner"],
    edit: ["owner", "editor"],
    view: ["owner", "editor", "viewer"]
  },

  // Optional: How permissions propagate through hierarchies
  hierarchyPropagation: {
    view: ["view"],  // view on parent → view on children
    edit: ["edit"]
  }
});

Step 3: Choose Storage Adapter

For development/testing:

import { InMemoryStorageAdapter } from "polizy";

const storage = new InMemoryStorageAdapter();

For production (Prisma):

import { PrismaAdapter } from "polizy/prisma-storage";
import { PrismaClient } from "@prisma/client";

const prisma = new PrismaClient();
const storage = PrismaAdapter(prisma);

See PRISMA-SETUP.md for Prisma model requirements.

Step 4: Create AuthSystem

import { AuthSystem } from "polizy";

const authz = new AuthSystem({
  storage,
  schema,
});

Step 5: Verify Setup

// Grant a permission
await authz.allow({
  who: { type: "user", id: "alice" },
  toBe: "owner",
  onWhat: { type: "document", id: "doc1" }
});

// Check it works
const canEdit = await authz.check({
  who: { type: "user", id: "alice" },
  canThey: "edit",
  onWhat: { type: "document", id: "doc1" }
});

console.log("Setup working:", canEdit); // true

Storage Decision Matrix

Factor	InMemoryStorageAdapter	PrismaAdapter
Persistence	No (lost on restart)	Yes
Multi-instance	No	Yes
Setup	Zero config	Requires Prisma model
Performance	Fastest	Database-dependent
Use case	Testing, dev	Production

Complete Minimal Setup

// auth.ts
import {
  defineSchema,
  AuthSystem,
  InMemoryStorageAdapter
} from "polizy";

const schema = defineSchema({
  relations: {
    owner: { type: "direct" },
    viewer: { type: "direct" },
  },
  actionToRelations: {
    edit: ["owner"],
    view: ["owner", "viewer"],
  },
});

const storage = new InMemoryStorageAdapter();

export const authz = new AuthSystem({ storage, schema });

Configuration Options

const authz = new AuthSystem({
  storage,
  schema,

  // Optional: Max depth for group/hierarchy traversal (default: 10)
  defaultCheckDepth: 10,

  // Optional: Throw error instead of returning false on max depth
  throwOnMaxDepth: false,

  // Optional: Field separator for field-level permissions (default: "#")
  fieldSeparator: "#",

  // Optional: Custom logger
  logger: {
    warn: (msg) => console.warn("[Polizy]", msg)
  }
});

Common Issues

Issue	Solution
"Cannot find module 'polizy'"	Run `npm install polizy`
TypeScript errors in schema	Ensure `defineSchema` is imported from "polizy"
Prisma model not found	See PRISMA-SETUP.md
Permission check returns false	Verify relation is in `actionToRelations` for that action

Next Steps

After setup, use these skills:

polizy-schema - Design your authorization model
polizy-patterns - Implement authorization scenarios
polizy-storage - Production storage setup

References

PRISMA-SETUP.md - Full Prisma configuration
FRAMEWORK-INTEGRATIONS.md - Next.js, Express examples

polizy-setup