skills/docs/identity/auth/permissions/src/schemas/permissions.schemas.md

permissions.schemas

(no submodules)

Purpose

Zod validation schemas for all public domain types and option bundles in @suaveplan/permissions. These schemas enable runtime validation of permissions data at system boundaries — configuration files, network payloads, database reads — and provide structured field-level error messages compatible with @suaveplan/error.

Features

• PermissionConditionSchema — validates condition operator and field name
• PermissionSchema — validates full permission record including optional conditions
• RoleSchema — validates role with permissions array and optional inheritance
• UserRoleSchema — validates user-role assignment with Date fields
• Option schemas for PermissionManager, RoleManager, PolicyEngine, PermissionCache
• Exported inferred TypeScript types

Usage: Basic Example

import { PermissionSchema } from "@suaveplan/permissions";

const result = PermissionSchema.safeParse({
  id: "p1",
  resource: "posts",
  action: "read",
});
if (!result.success) console.error(result.error.flatten());

Usage: Advanced Example

import { RoleSchema } from "@suaveplan/permissions";

const role = RoleSchema.parse({
  id: "editor",
  name: "Editor",
  permissions: [{ id: "p1", resource: "posts", action: "write" }],
  inherits: ["viewer"],
});

API Reference

ConditionOperatorSchema — enum of 12 operators

PermissionConditionSchema — { field, operator, value }

PermissionSchema — { id, resource, action, conditions?, description? }

RoleSchema — { id, name, permissions, inherits?, metadata?, isSystem?, siteId? }

UserRoleSchema — { id, userId, roleId, siteId?, assignedAt: Date, expiresAt?: Date, assignedBy? }

PermissionCacheOptionsSchema — { ttl, maxSize? }

Implementation Notes

The PermissionActionSchema uses a union of the canonical enum and a general z.string().min(1) to allow custom action strings beyond the predefined set. Option schemas use z.unknown() for injectable dependencies (event bus, cache) to avoid circular Zod schema references.