Lesson 5 - Add Permissions and Guardrails

In this lesson, we’ll introduce authentication and access control - making this blueprint safe to use for the team.

Keep editing in the Playground. In this lesson, you will tighten access around the entity and pages you already have, and test as much of it as the sandbox allows.

The Goal

By the end of this lesson, you’ll have explored:

• who can submit requests
• who can review requests
• who can approve unusual cases
• which pages should require authentication

Authorization and Authentication

This lesson covers two related but different concerns:

• Authorization — once someone is using the tool, what are they allowed to see or change? This is entity-level access control, driven by $currentUser.role. You can fully test this in the Playground by switching accounts in the toolbar.
• Authentication — is there a real person signed in at all? This depends on a working sign-in form backed by a real session, which only exists once you run the blueprint with the CLI in Lesson 6. The Playground can prove the gate fires — switch the Account dropdown to Anonymous and confirm you get redirected away from a page marked auth = "required" — but it will not show you a working login screen, because there is no real account system in the browser sandbox.

We’ll save the demonstration that authentication works until Lesson 6 - but we can test and verify authorization in this lesson.

Add Entity Access Rules

We need to figure out who has access to what.

For HarborFlow, Taylor wants:

• broad internal visibility
• narrower update rights
• explicit approval ownership for exceptional requests

One reasonable first pass is:

[entities.access]
read = true
create = true
update = { or = [{ "$currentUser.role" = "manager" }, { "$currentUser.role" = "admin" }] }
delete = { "$currentUser.role" = "admin" }

Add this access block directly below the [[entities]] entry where name = "ExceptionRequest".

Recall from Lesson 2 that the Playground’s account switcher offers requester, manager, and admin — standing in for HarborFlow’s account managers, ops managers, and directors. That is why the access rule above checks role = "manager" and role = "admin" instead of made-up strings like ops_manager: those are the exact personas you can pick from the toolbar to test the rule for real.

Try it now: switch to Requester and confirm you cannot change a request’s status. Switch to Manager or Admin and confirm you can. That immediate feedback loop is the reason this part of the lesson lives in the Playground.

If your process needs tighter controls, ask these types of questions:

• should submitters only see requests they created?
• should reviewers be able to edit every field or only status and notes?
• should directors be the only people allowed to approve high-priority requests?

Add Page-Level Authentication

Require authentication on the working pages so the tool is not public:

[[pages]]
path = "/"
title = "Customer Exception Requests"
layout = "list"
auth = "required"

Flip the auth flag from “optional” to “required” for the list, form, and detail pages you built in Lesson 4.

Add a minimal auth block alongside it, although it will not fully resolve until you run this from the command line:

[auth]
providers = ["email"]
trustedOrigins = ["http://localhost:3000"]

[[pages]]
path = "/sign-in"
title = "Sign In"
layout = "auth"

In the Playground, switch the Account dropdown to Anonymous and try to open one of these pages. You should get redirected away — that confirms the required authentication is active. You will not see a working sign-in form yet; that requires the real engine, which is in Lesson 6.

HarborFlow Guardrail Questions

Use questions like these:

• should submitters be able to edit requests after review starts?
• should every employee be able to see every request?
• who can move a request from reviewing to approved?
• do rejected requests need a visible reason?

These are all realistic considerations for an internal operations tool once it gets past a proof of concept.

Version 1.0 Permissions

After going through this exercise, you’ll have some strong security improvements:

• the app is no longer accidentally open
• the review flow has clear ownership
• the team can use the tool without obvious security objections

Lesson Output

By the end of this lesson, you should have:

• entity access rules you have personally verified by switching accounts in the Playground
• page-level auth = "required" and a minimal [auth] block, verified only as far as the sandbox allows
• a clearer understanding of who owns each step in the workflow

Use Security & Authentication for the exact access-control patterns Zebric supports.

What Changes In blueprint.toml

In this lesson, you are adding security-related sections:

• add [entities.access] rules for CRUD behavior under the ExceptionRequest entity, using requester/manager/admin as the role values
• add an [auth] block and a /sign-in page
• change working pages from auth = "optional" to auth = "required"

Checkpoint Blueprint

Use lesson-5-blueprint.toml if you want a complete, working file with entity access rules, required page auth, and a sign-in page.

The checkpoint should validate cleanly:

zebric validate --blueprint lesson-5-blueprint.toml

Zebric Concepts In This Lesson

• Access Control: entity-level read, create, update, and delete rules — fully testable via the Playground’s account switcher
• Authentication: page-level sign-in requirements and auth pages — configured here, verified for real once you leave the sandbox
• Pages: auth requirements now shape who can reach the workflow UI
• Entities: access rules define who can change workflow state

Next Lesson

Continue to Lesson 6 - Add Your First High-Leverage Workflow.