permission.mdx

title	Permission
description	Permission protocol schemas

{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}

Entity (Object) Level Permissions

Defines CRUD + VAMA (View All / Modify All) + Lifecycle access.

Refined with enterprise data lifecycle controls:

• Transfer (Ownership change)

• Restore (Soft delete recovery)

• Purge (Hard delete / Compliance)

**Source:** `packages/spec/src/security/permission.zod.ts`

TypeScript Usage

import { AdminScope, EffectiveObjectPermission, FieldPermission, ObjectAccessScope, ObjectPermission, PermissionSet } from '@objectstack/spec/security';
import type { AdminScope, EffectiveObjectPermission, FieldPermission, ObjectAccessScope, ObjectPermission, PermissionSet } from '@objectstack/spec/security';

// Validate data
const result = AdminScope.parse(data);

---

AdminScope

Properties

Property	Type	Required	Description
businessUnit	string	✅	[ADR-0090 D12] Delegation boundary: sys_business_unit.name of the subtree root
includeSubtree	boolean	✅	Cover descendant business units too (default true)
manageAssignments	boolean	✅	Manage user↔position assignments within the subtree
manageBindings	boolean	✅	Manage position↔permission-set bindings within the subtree
authorEnvironmentSets	boolean	✅	Author environment-owned permission sets
assignablePermissionSets	string[]	✅	Allowlist of permission-set names the delegate may hand out

---

EffectiveObjectPermission

Properties

Property	Type	Required	Description
allowCreate	boolean	✅	Create permission
allowRead	boolean	✅	Read permission
allowEdit	boolean	✅	Edit permission
allowDelete	boolean	✅	Delete permission
allowExport	boolean	optional	[#3544] User-level export axis over read. Unset = inherit read (can-list ⇒ can-export, backward-compatible); false = deny export while keeping read; true = granted.
allowTransfer	boolean	✅	[RBAC-gated; ENFORCED now via insert/update owner_id guard, #3004] Change record ownership (assign/reassign/disown owner_id)
allowRestore	boolean	✅	[RBAC-gated; operation pending M2] Restore from trash (Undelete)
allowPurge	boolean	✅	[RBAC-gated; operation pending M2] Permanently delete (Hard Delete/GDPR)
viewAllRecords	boolean	✅	View All Data (Bypass Sharing)
modifyAllRecords	boolean	✅	Modify All Data (Bypass Sharing)
readScope	Enum<'own' | 'own_and_reports' | 'unit' | 'unit_and_below' | 'org'>	optional	[ADR-0057 D1] Read depth: own|unit|unit_and_below|org
writeScope	Enum<'own' | 'own_and_reports' | 'unit' | 'unit_and_below' | 'org'>	optional	[ADR-0057 D1] Write depth: own|unit|unit_and_below|org
apiOperations	Enum<'get' | 'list' | 'create' | 'update' | 'delete' | 'upsert' | 'bulk' | 'aggregate' | 'history' | 'search' | 'restore' | 'purge' | 'import' | 'export'>[]	optional	Server-resolved effective API operations for this object (#3391). Present only when the object tightens exposure via apiMethods; absent = default-allow. The frontend renders this effective set, never the raw whitelist. Vocabulary is the EFFECTIVE ApiOperation set (six primitives + eight derived verbs, #3543), not the authored six-value ApiMethod enum.

---

FieldPermission

Properties

Property	Type	Required	Description
readable	boolean	✅	Field read access
editable	boolean	✅	Field edit access

---

ObjectAccessScope

Allowed Values

• own
• own_and_reports
• unit
• unit_and_below
• org

---

ObjectPermission

Properties

Property	Type	Required	Description
allowCreate	boolean	✅	Create permission
allowRead	boolean	✅	Read permission
allowEdit	boolean	✅	Edit permission
allowDelete	boolean	✅	Delete permission
allowExport	boolean	optional	[#3544] User-level export axis over read. Unset = inherit read (can-list ⇒ can-export, backward-compatible); false = deny export while keeping read; true = granted.
allowTransfer	boolean	✅	[RBAC-gated; ENFORCED now via insert/update owner_id guard, #3004] Change record ownership (assign/reassign/disown owner_id)
allowRestore	boolean	✅	[RBAC-gated; operation pending M2] Restore from trash (Undelete)
allowPurge	boolean	✅	[RBAC-gated; operation pending M2] Permanently delete (Hard Delete/GDPR)
viewAllRecords	boolean	✅	View All Data (Bypass Sharing)
modifyAllRecords	boolean	✅	Modify All Data (Bypass Sharing)
readScope	Enum<'own' | 'own_and_reports' | 'unit' | 'unit_and_below' | 'org'>	optional	[ADR-0057 D1] Read depth: own|unit|unit_and_below|org
writeScope	Enum<'own' | 'own_and_reports' | 'unit' | 'unit_and_below' | 'org'>	optional	[ADR-0057 D1] Write depth: own|unit|unit_and_below|org

---

PermissionSet

Properties

Property	Type	Required	Description
name	string	✅	Permission set unique name (lowercase snake_case)
label	string	optional	Display label
packageId	string	optional	[ADR-0086 D3] Owning package id for a package-shipped set (absent = env-authored)
managedBy	Enum<'package' | 'platform' | 'user'>	optional	[ADR-0086 D3] Record provenance: package (upgrade-owned metadata) vs platform/user (env config)
isDefault	boolean	✅	[ADR-0090 D5] App baseline for the everyone position: app-level sets are auto-bound at boot (guarded, idempotent); package-level sets become install-time suggestions an admin confirms
objects	Record<string, { allowCreate: boolean; allowRead: boolean; allowEdit: boolean; allowDelete: boolean; … }>	✅	Entity permissions
fields	Record<string, { readable: boolean; editable: boolean }>	optional	Field level security
systemPermissions	string[]	optional	System level capabilities
tabPermissions	Record<string, Enum<'visible' | 'hidden' | 'default_on' | 'default_off'>>	optional	App/tab visibility: visible, hidden, default_on (shown by default), default_off (available but hidden initially)
rowLevelSecurity	{ name: string; label?: string; description?: string; object: string; … }[]	optional	Row-level security policies (see rls.zod.ts for full spec)
adminScope	{ businessUnit: string; includeSubtree: boolean; manageAssignments: boolean; manageBindings: boolean; … }	optional	[ADR-0090 D12] Scoped delegated-administration grant (BU subtree + assignable-set allowlist)

---