Build a Real-Time Permissions System with Zanzibar

// src/authz/types.ts
import { z } from 'zod';

// Zanzibar-style relationship tuple: user/group has relation to object
export const RelationTuple = z.object({
  object: z.string(),       // "document:report-2024"
  relation: z.string(),     // "editor"
  subject: z.string(),      // "user:alice" or "team:engineering#member"
});

// Authorization model: defines which relations exist and how they inherit
export const AuthzModel = z.object({
  types: z.record(z.string(), z.object({
    relations: z.record(z.string(), z.object({
      directlyAssignable: z.boolean().default(true),
      // Union: this relation includes users from other relations
      union: z.array(z.string()).optional(),
      // Intersection: user must have ALL of these relations
      intersection: z.array(z.string()).optional(),
      // Parent: inherit from parent object's relation
      fromParent: z.object({
        parentRelation: z.string(),
        parentType: z.string(),
        inheritedRelation: z.string(),
      }).optional(),
    })),
  })),
});

// Example model
export const model: z.infer<typeof AuthzModel> = {
  types: {
    organization: {
      relations: {
        owner: { directlyAssignable: true },
        admin: { directlyAssignable: true, union: ['owner'] },
        member: { directlyAssignable: true, union: ['admin'] },
      },
    },
    project: {
      relations: {
        parent_org: { directlyAssignable: true },
        admin: {
          directlyAssignable: true,
          // Org admins are project admins
          fromParent: { parentRelation: 'parent_org', parentType: 'organization', inheritedRelation: 'admin' },
        },
        editor: { directlyAssignable: true, union: ['admin'] },
        viewer: { directlyAssignable: true, union: ['editor'] },
      },
    },
    document: {
      relations: {
        parent_project: { directlyAssignable: true },
        owner: { directlyAssignable: true },
        editor: {
          directlyAssignable: true,
          union: ['owner'],
          fromParent: { parentRelation: 'parent_project', parentType: 'project', inheritedRelation: 'editor' },
        },
        viewer: {
          directlyAssignable: true,
          union: ['editor'],
          fromParent: { parentRelation: 'parent_project', parentType: 'project', inheritedRelation: 'viewer' },
        },
      },
    },
  },
};

// src/authz/checker.ts
import { Pool } from 'pg';
import { Redis } from 'ioredis';

const db = new Pool({ connectionString: process.env.DATABASE_URL });
const redis = new Redis(process.env.REDIS_URL!);

export async function check(
  object: string,
  relation: string,
  subject: string
): Promise<boolean> {
  // Check cache first (5-second TTL)
  const cacheKey = `authz:${object}:${relation}:${subject}`;
  const cached = await redis.get(cacheKey);
  if (cached !== null) return cached === '1';

  const result = await resolveCheck(object, relation, subject, new Set());

  // Cache result
  await redis.setex(cacheKey, 5, result ? '1' : '0');
  return result;
}

async function resolveCheck(
  object: string,
  relation: string,
  subject: string,
  visited: Set<string>
): Promise<boolean> {
  const visitKey = `${object}:${relation}:${subject}`;
  if (visited.has(visitKey)) return false; // prevent cycles
  visited.add(visitKey);

  // Direct check: is there a tuple (object, relation, subject)?
  const { rows } = await db.query(`
    SELECT 1 FROM relation_tuples
    WHERE object = $1 AND relation = $2 AND subject = $3
    LIMIT 1
  `, [object, relation, subject]);

  if (rows.length > 0) return true;

  // Check group membership: subject might be "team:eng#member"
  // If subject is "user:alice", check if alice is a member of any group that has this relation
  const { rows: groupTuples } = await db.query(`
    SELECT rt.subject FROM relation_tuples rt
    WHERE rt.object = $1 AND rt.relation = $2 AND rt.subject LIKE '%#%'
  `, [object, relation]);

  for (const gt of groupTuples) {
    const [groupObj, groupRel] = gt.subject.split('#');
    const isMember = await resolveCheck(groupObj, groupRel, subject, visited);
    if (isMember) return true;
  }

  // Check relation inheritance (union)
  const [objectType] = object.split(':');
  const modelType = model.types[objectType];
  if (!modelType) return false;

  const relationDef = modelType.relations[relation];
  if (!relationDef) return false;

  // Union: check if subject has any of the parent relations
  if (relationDef.union) {
    for (const parentRelation of relationDef.union) {
      const has = await resolveCheck(object, parentRelation, subject, visited);
      if (has) return true;
    }
  }

  // Parent inheritance
  if (relationDef.fromParent) {
    const { parentRelation, parentType, inheritedRelation } = relationDef.fromParent;
    const { rows: parents } = await db.query(`
      SELECT subject FROM relation_tuples WHERE object = $1 AND relation = $2
    `, [object, parentRelation]);

    for (const parent of parents) {
      const hasInherited = await resolveCheck(parent.subject, inheritedRelation, subject, visited);
      if (hasInherited) return true;
    }
  }

  return false;
}

// Import model
import { model } from './types';

// src/authz/middleware.ts
import { check } from './checker';

export function authorize(objectFn: (c: any) => string, relation: string) {
  return async (c: any, next: any) => {
    const userId = c.get('userId');
    if (!userId) return c.json({ error: 'Unauthorized' }, 401);

    const object = objectFn(c);
    const allowed = await check(object, relation, `user:${userId}`);

    if (!allowed) return c.json({ error: 'Forbidden' }, 403);
    await next();
  };
}

// Usage:
// app.get('/documents/:id', authorize(c => `document:${c.req.param('id')}`, 'viewer'), handler)
// app.put('/documents/:id', authorize(c => `document:${c.req.param('id')}`, 'editor'), handler)