first commit

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

@@ -0,0 +1,61 @@
+# permissions.schemas
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## 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
+
+```ts
+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
+
+```ts
+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.