Match Project Stakeholder

The Match Project Stakeholder (matchProjectStakeholder) access rule implements a compound access check that grants access to a project record when the authenticated caller is either the direct owner OR an explicit project member, regardless of role.

In team and project collaboration software, users often need to see and manage projects they created and projects they were invited to join. Because neither direct ownership (matchResourceOwner) nor membership checks (matchProjectRole) cover this union on their own, Match Project Stakeholder evaluates both criteria simultaneously.

---

1. How It Works

• Compound Evaluation: The engine verifies whether the caller’s User ID matches the project’s owner foreign key OR exists in the project’s membership join table.
• Synchronous Collection Scoping (FETCH): On collection queries (list, search, restore), the engine injects a single compound SQL predicate:

  WHERE (
    projects.owner_id = :currentUserId
    OR EXISTS (
      SELECT 1 FROM project_members
      WHERE project_members.project_id = projects.id
        AND project_members.user_id = :currentUserId
    )
  )

• Pre-Flight Record Checks (PRE_FETCH): On single-resource actions (read, update, delete), the engine executes an asynchronous pre-flight database lookup ensuring the target record satisfies either condition before executing the operation.
• Exact Pagination: Because the compound check is injected directly into SQL during the FETCH phase, pagination totals (meta.total, page, per_page) remain 100% exact.

Property	Specification
Rule Type	matchProjectStakeholder
Supported Strategies	All strategies (RBAC, OrganizationRBAC, EnterpriseRBAC)
Allowed Placement Levels	Exposed Entity Level (exposure), Action Level (action) (Not allowed at global API Model Level)
Execution Phases	FETCH (list, search, restore), PRE_FETCH (read, update, delete)

---

2. Prerequisites in the Data Domain

To use Match Project Stakeholder, your Data Domain must define:

1. Project: An entity representing the collaboration unit.
2. User: An entity representing system users.
3. At least one of the following semantic modules attached to the Project entity:
   • ResourceOwnerIdentifier: A direct association linking Project to User identifying the owner.
   • ProjectMembers: A Many-to-Many (multiple: true) association linking Project to User managing collaborators.

---

3. Partial Semantic Resolution

Match Project Stakeholder adapts dynamically to whichever semantics are configured on the entity:

Domain Configuration	Runtime Behavior
Both ResourceOwnerIdentifier and ProjectMembers present	Evaluates full compound owner OR member disjunction.
Only ResourceOwnerIdentifier present	Evaluates ownership leg only (equivalent to matchResourceOwner).
Only ProjectMembers present	Evaluates membership leg only (equivalent to matchProjectRole without role restrictions).
Neither present	Fails fast (500 Internal Server Error) indicating misconfigured domain semantics.

---

4. Creation Actions (create)

create Actions Do Not Use Match Project Stakeholder

Match Project Stakeholder cannot be used on create (POST) actions because the project record does not exist in the database prior to execution.

How creation is handled instead:

1. Gate the create action using Allow Authenticated or Match User Role.
2. Tag the owner foreign key with the ResourceOwnerIdentifier semantic module. The platform will automatically assign the authenticated user’s ID as the owner upon creation.

---

5. Comparison Matrix

Feature	Match Resource Owner (matchResourceOwner)	Match Project Role (matchProjectRole)	Match Project Stakeholder (matchProjectStakeholder)
Evaluates Ownership	✅ Yes (Direct FK)	❌ No	✅ Yes (Direct FK)
Evaluates Membership	❌ No	✅ Yes (Pivot table)	✅ Yes (Pivot table)
Role Verification	N/A	✅ Can restrict to specific roles (e.g. admin, editor)	Any membership qualifies
Use Case	Personal resources (notes, personal profiles)	Role-restricted team operations (e.g. only project managers can delete)	Unified workspace listing (“Projects I own or joined”)

---

Next Steps

• Getting Started with Authorization: Learn how Access Scenarios and Predicate Trees evaluate permissions.
• Match Project Role: Restrict operations by specific project roles.
• Match Resource Owner: Enforce direct ownership on individual resources.