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

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

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

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