Polizy Storage

Polizy Storage

Storage adapters handle persistence of authorization tuples.

When to Apply

• User asks "set up database storage"
• User asks "use Prisma with polizy"
• User asks "create custom storage adapter"
• User asks about "production storage"
• User has performance concerns with authorization

Adapter Comparison

Quick Setup

InMemory (Development/Testing)

import { AuthSystem, InMemoryStorageAdapter } from "polizy";

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

Prisma (Production)

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

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

Requires Prisma model - see PRISMA-ADAPTER.md

InMemoryStorageAdapter

When to Use

• Unit tests
• Development environment
• Single-process applications
• Prototyping

Behavior

• Data stored in JavaScript Map
• Lost on process restart
• No network latency
• Fastest possible reads
• Returns live references — treat results as immutable; use withSnapshot for an isolated copy.

Testing Example

import { describe, it, beforeEach } from "node:test";
import { AuthSystem, InMemoryStorageAdapter, defineSchema } from "polizy";

describe("authorization", () => {
  let authz: AuthSystem<typeof schema>;

  beforeEach(() => {
    // Fresh storage for each test
    const storage = new InMemoryStorageAdapter();
    authz = new AuthSystem({ storage, schema });
  });

  it("grants access correctly", async () => {
    await authz.allow({
      who: { type: "user", id: "alice" },
      toBe: "owner",
      onWhat: { type: "doc", id: "doc1" }
    });

    const result = await authz.check({
      who: { type: "user", id: "alice" },
      canThey: "edit",
      onWhat: { type: "doc", id: "doc1" }
    });

    assert.strictEqual(result, true);
  });
});

PrismaAdapter

When to Use

• Production environments
• Multi-instance deployments
• Need audit trail
• Data must survive restarts

Setup Steps

1. Install dependencies

   npm install @prisma/client
   npm install -D prisma
   

2. Add Prisma model (see PRISMA-ADAPTER.md)

3. Run migrations

   npx prisma migrate dev --name add_polizy
   

4. Use adapter

   import { PrismaAdapter } from "polizy/prisma-storage";
   const storage = PrismaAdapter(prisma);
   

Storage Interface

All adapters implement the same contract. You can validate any custom adapter using the published contract test suite polizy/storage-tests. The bundled InMemoryStorageAdapter and PrismaAdapter are both held to this contract, so they behave identically:

interface StorageAdapter<S, O> {
  // Idempotent on (subject, relation, object). Re-writing updates the
  // condition, never duplicates. Returns stored tuples in input order.
  write(tuples: InputTuple<S, O>[]): Promise<StoredTuple<S, O>[]>;

  // (who? subject==who) AND (was? relation==was)
  //   AND (onWhat? object==onWhat OR subject==onWhat).
  // An explicit `who` is never dropped — the subject-position arm of `onWhat`
  // only fires when `who` is absent. Returns the number deleted.
  delete(filter: {
    who?: Subject<S> | AnyObject<O>;
    was?: Relation;
    onWhat?: AnyObject<O>;
  }): Promise<number>;

  // Supports { limit, offset } pagination in stable order.
  findTuples(
    filter: Partial<InputTuple<S, O>>,
    options?: { limit?: number; offset?: number },
  ): Promise<StoredTuple<S, O>[]>;

  findSubjects(object, relation, options?: { subjectType?: S }): Promise<Subject<S>[]>;
  findObjects(subject, relation, options?: { objectType?: O }): Promise<AnyObject<O>[]>;
}

See CUSTOM-ADAPTERS.md for the exact idempotent-write, delete, and pagination semantics every adapter must honor.

Role catalog (runtime roles)

When you use RoleRegistry for runtime custom roles, an optional RoleCatalogStore tracks role existence + labels. This is metadata only — the engine never reads the catalog. Capabilities (cap_<action> tuples) and assignments (assignee membership tuples) live as ordinary tuples in the StorageAdapter, so a role is fully functional even with no catalog at all. The catalog exists so permission-less roles stay listable (e.g. a freshly-created role with no caps yet still shows up in listRoles/permissionMatrix).

Note that InMemoryRoleCatalog composite key separator is written as the unicode escape sequence \u0000 in source (never as an actual control character).

// Dev / tests: in-memory catalog
import { AuthSystem, InMemoryStorageAdapter, InMemoryRoleCatalog, RoleRegistry } from "polizy";

const authz = new AuthSystem({ storage: new InMemoryStorageAdapter(), schema });
const roles = new RoleRegistry(authz, schema, { catalog: new InMemoryRoleCatalog() });

// Production: Prisma-backed catalog
import { AuthSystem, RoleRegistry } from "polizy";
import { PrismaAdapter, PrismaRoleCatalog } from "polizy/prisma-storage";
import { PrismaClient } from "@prisma/client";

const prisma = new PrismaClient();
const authz = new AuthSystem({ storage: PrismaAdapter(prisma), schema });
const roles = new RoleRegistry(authz, schema, { catalog: PrismaRoleCatalog(prisma) });

PrismaRoleCatalog needs the new optional PolizyRole Prisma model — see PRISMA-ADAPTER.md. The catalog is independent of the tuple StorageAdapter: you can pair an in-memory catalog with a Prisma adapter or vice versa, since the engine resolves roles purely from tuples.

Common Patterns

Shared Storage Instance

// storage.ts
import { InMemoryStorageAdapter } from "polizy";
// or: import { PrismaAdapter } from "polizy/prisma-storage";

export const storage = new InMemoryStorageAdapter();
// or: export const storage = PrismaAdapter(prisma);

// auth.ts
import { AuthSystem } from "polizy";
import { storage } from "./storage";
import { schema } from "./schema";

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

Environment-Based Selection

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

function createStorage() {
  if (process.env.NODE_ENV === "test") {
    return new InMemoryStorageAdapter();
  }

  const prisma = new PrismaClient();
  return PrismaAdapter(prisma);
}

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

Performance Considerations

check() is memoized per call (no exponential blow-up on deep/wide group or hierarchy graphs; cycles terminate), and listAccessibleObjects scales with the subject's reachable set rather than scanning the whole tuple table. See PERFORMANCE.md.

Common Issues

References

• PRISMA-ADAPTER.md - Full Prisma setup (with transactionOptions config)
• CUSTOM-ADAPTERS.md - Building custom adapters & testing with polizy/storage-tests
• PERFORMANCE.md - Optimization strategies

Related Skills

• polizy-setup - Initial setup
• polizy-troubleshooting - Debugging