apairon
491f495c66
- Updated `tibi-project-setup` skill to clarify project initialization goals and steps. - Improved `tibi-ssr-caching` skill to detail SSR architecture, responsibilities, and caching mechanisms. - Introduced `website-solution-architecture` skill for translating website requirements into coherent solutions. - Refined `AGENTS.md` to provide a structured roadmap for project development phases. - Added `ADMIN_ASSET_VERSION` to `api/config.yml.env` for asset versioning. - Updated SSR request flow and cache invalidation logic in `api/hooks/ssr/AGENTS.md`. - Removed obsolete `esbuild.config.admin.js` and integrated asset versioning into the main `esbuild.config.js`. - Adjusted `api/collections/content.yml` to utilize asset versioning for admin scripts.
182 lines
6.0 KiB
Markdown
182 lines
6.0 KiB
Markdown
---
|
|
name: permissions-and-editor-workflows
|
|
description: Design safe editor workflows with current tibi-server permissions and Nova authoring patterns. Covers collection permissions, field-level readonly/hidden rules, roles, tokens, and how admin UX should reflect real editorial boundaries.
|
|
---
|
|
|
|
# permissions-and-editor-workflows
|
|
|
|
## When to use this skill
|
|
|
|
Use this skill when:
|
|
|
|
- A project needs more than one editor/admin role
|
|
- Collections or fields should be restricted by role or token
|
|
- You need readonly/hidden field logic for real editorial workflows
|
|
- You want Nova UX to reflect actual server-side permissions instead of pretending every field is editable
|
|
|
|
## Goal
|
|
|
|
The goal is to design permissions as part of the editorial workflow, not as a last-minute access check.
|
|
|
|
On this stack, permissions affect:
|
|
|
|
- API methods
|
|
- field visibility
|
|
- field editability
|
|
- collection visibility
|
|
- token-based integrations
|
|
- admin usability
|
|
|
|
## Source of truth
|
|
|
|
Use these sources when implementing or reviewing permissions:
|
|
|
|
- `tibi-server/docs/17-field-level-permissions.md`
|
|
- `tibi-server/docs/05-authentication.md`
|
|
- relevant collection YAML files
|
|
- `tibi-admin-nova/types/admin.d.ts`
|
|
|
|
## Permission layers
|
|
|
|
At minimum, reason about permissions on these levels:
|
|
|
|
- collection methods (`get`, `post`, `put`, `delete`)
|
|
- field-level `readonlyFields`
|
|
- field-level `hiddenFields`
|
|
- field-definition overrides (`readonly`, `hidden`)
|
|
- dynamic eval-based field rules
|
|
- collection `meta.hide` for sidebar visibility
|
|
|
|
Do not flatten all of this into one vague notion of “editor access”.
|
|
|
|
## Collection-level workflow design
|
|
|
|
Before implementing permissions, define who does what.
|
|
|
|
Typical roles/workflows:
|
|
|
|
- public readers
|
|
- editors creating and updating content
|
|
- reviewers or restricted staff
|
|
- admins configuring structure and sensitive fields
|
|
- token-based integrations
|
|
|
|
Then map those responsibilities to explicit permission sets.
|
|
|
|
## Field-level permissions
|
|
|
|
Current tibi-server field permissions are strong and should be used deliberately.
|
|
|
|
Important behavior:
|
|
|
|
- `readonlyFields`: writes fail with `400` if those fields are sent
|
|
- `hiddenFields`: writes fail with `400`, reads strip the fields from responses
|
|
- field-level `readonly` / `hidden` can override or dynamically extend behavior
|
|
|
|
This means field permissions are not mere UI hints. They are enforced server-side.
|
|
|
|
## Dynamic field rules
|
|
|
|
Use eval-based field rules when permissions depend on document state.
|
|
|
|
Typical examples:
|
|
|
|
- a field becomes readonly after approval
|
|
- an internal note is hidden from non-admin roles
|
|
- a billing field is editable only before status changes
|
|
|
|
Use these rules to model real editorial transitions, not to create confusing surprises.
|
|
|
|
## Admin UX must reflect permission reality
|
|
|
|
If a field is hidden or readonly for a role, the Nova configuration and layout should support that reality.
|
|
|
|
Recommended patterns:
|
|
|
|
- keep critical restricted fields out of primary editorial flow
|
|
- place admin-only or system-managed fields in sidebars or dedicated sections
|
|
- avoid forms whose main content becomes unusable when half the fields are hidden by role
|
|
- design previews so editors can still identify entries even when some internal fields are hidden
|
|
|
|
Server permissions are authoritative, but poor admin layout can still create a bad workflow.
|
|
|
|
## Tokens and integrations
|
|
|
|
Remember that token-based integrations can have their own permission sets.
|
|
|
|
Use this for:
|
|
|
|
- inbound integrations
|
|
- service accounts
|
|
- controlled automation
|
|
- frontend-to-backend machine use cases when appropriate
|
|
|
|
Do not reuse broad admin permissions for integrations if a narrow token permission set is enough.
|
|
|
|
## Permission-driven architecture decisions
|
|
|
|
Permissions can change the correct data model.
|
|
|
|
Examples:
|
|
|
|
- if sensitive internal notes should never be visible to normal editors, consider whether they belong in the same collection or a separate one
|
|
- if a public form creates internal records, the public action and the internal collection should have separate permission boundaries
|
|
- if a workflow has approval stages, model status transitions and readonly behavior explicitly
|
|
|
|
## Recommended patterns
|
|
|
|
### Editorial content workflow
|
|
|
|
Recommended shape:
|
|
|
|
- editors can create and update content fields
|
|
- publication/system fields may be restricted or conditionally readonly
|
|
- admin-only technical fields are hidden or isolated in the UI
|
|
|
|
### Sensitive internal data
|
|
|
|
Recommended shape:
|
|
|
|
- hide internal-only fields from normal editors
|
|
- prefer explicit server-side rules over relying on UI omission
|
|
- ensure previews do not depend on hidden-only data
|
|
|
|
### Approval-style workflow
|
|
|
|
Recommended shape:
|
|
|
|
- status field controls editability of specific fields
|
|
- post-approval fields become readonly via eval rules
|
|
- admin or reviewer roles retain the intended override path
|
|
|
|
## Anti-patterns
|
|
|
|
- Treating permissions as frontend-only display logic
|
|
- Leaving sensitive fields visible and merely asking editors not to touch them
|
|
- Using one broad admin token for every integration
|
|
- Designing forms that depend on fields many roles cannot access
|
|
- Adding dynamic readonly/hidden logic without explaining the editorial workflow it represents
|
|
|
|
## Verification checklist
|
|
|
|
After changing permissions or editor workflows, verify all of these:
|
|
|
|
1. Collection methods match the intended role model.
|
|
2. Hidden and readonly field behavior is correct on API reads/writes.
|
|
3. Dynamic eval rules behave correctly for the intended document states.
|
|
4. Nova forms remain usable for the non-admin roles that actually work there.
|
|
5. Token/integration permissions are narrower than admin access when possible.
|
|
6. `yarn validate` stays clean.
|
|
|
|
## What an LLM should inspect first
|
|
|
|
When asked to design permissions on this starter, inspect in this order:
|
|
|
|
1. the relevant collection YAML
|
|
2. the intended human roles and machine integrations
|
|
3. field-level readonly/hidden needs
|
|
4. whether the current Nova layout still makes sense under those restrictions
|
|
5. any workflow states that require dynamic eval rules
|
|
|
|
This prevents access rules that are technically correct but operationally unusable.
|