docs(authz): custom resource loading and role inheritance by whoAbhishekSah · Pull Request #1713 · raystack/frontier

whoAbhishekSah · 2026-06-30T04:16:29Z

What

Adds a new authz doc: docs/content/docs/authz/custom-resources.mdx.

It explains how custom resource types work end to end.

Notes

Docs only. No code changes.

Add a doc covering how custom resource types are registered, what SpiceDB rules the bootstrap generator creates for each action, and which role each action ends up with. It also explains why an Org Admin can list resources but cannot get a single one: listing accepts app_project_get as org-wide visibility, while the per-resource get check does not. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Add a "project-level actions" section explaining that create and list are not special permissions. By RBAC nature they need an object to check against, and the natural object is the container (the project), not a not-yet-created item or a single item. Document the user/project namespace as a config-legal proxy for app/project, since app/* permissions cannot be added from config, with a compute/machine example for create and list. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

vercel · 2026-06-30T04:16:35Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
frontier	Ready	Preview, Comment	Jul 6, 2026 8:15am

coderabbitai · 2026-06-30T04:16:49Z

📝 Walkthrough

Summary by CodeRabbit

Documentation
- Added detailed guidance for configuring custom resource types and actions.
- Expanded coverage of how authorization rules and permission slugs are generated and applied.
- Clarified role behavior for common actions, including differences between owner/admin access and project-level permissions.
- Included examples for project-wide actions, check routing, and how to use built-in roles versus custom roles.

Walkthrough

Adds a new MDX documentation page about custom resource authorization, covering schema bootstrap, generated permission rules, role inheritance, the user/project proxy for project-level actions, and a quick reference summary.

Changes

Custom Resources Authorization Documentation

Layer / File(s)	Summary
Custom resource loading and bootstrap pipeline `docs/content/docs/authz/custom-resources.mdx`	Adds page metadata, config-driven namespace/action definitions, and the `MigrateSchema` bootstrap flow from config parsing through schema merging, validation, and writes to Postgres and SpiceDB.
Generated permission structure and role inheritance `docs/content/docs/authz/custom-resources.mdx`	Documents the generated rule placements for each custom action, slug flattening, and the difference between Org Owner and Org Admin inheritance for custom actions.
Project-level action modeling via `user/project` proxy `docs/content/docs/authz/custom-resources.mdx`	Explains the `user/project` proxy namespace for `create` and `list`, the `app/*` restriction, and how project-scoped capabilities are mirrored onto `app/project` checks.
Default principals and quick reference `docs/content/docs/authz/custom-resources.mdx`	Lists the default principals, the config-grant paths for other roles, and the closing quick reference summary.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 2

✅ Passed checks (2 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

coderabbitai

Actionable comments posted: 2

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: ad01aca0-a127-489d-9266-8ee8529458a1

📥 Commits

Reviewing files that changed from the base of the PR and between 6dc16f9 and 5e574e0.

📒 Files selected for processing (1)

docs/content/docs/authz/custom-resources.mdx

Remove the "listing vs getting" section. The list-can-succeed-while-get-fails behaviour it described is likely a bug, not something to document as expected. Replace the mermaid load-flow diagram with a plain-text diagram so it renders the same in light and dark theme. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

coveralls · 2026-06-30T04:23:08Z

Coverage Report for CI Build 28777571430

Coverage remained the same at 44.865%

Details

Coverage remained the same as the base build.
Patch coverage: No coverable lines changed in this PR.
No coverage regressions found.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

No coverage regressions found.

Coverage Stats


Relevant Lines:	37608
Covered Lines:	16873
Line Coverage:	44.87%
Coverage Strength:	12.49 hits per line

💛 - Coveralls

coderabbitai

Actionable comments posted: 1

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 118547e3-ec36-401c-8807-1a757d1b759a

📥 Commits

Reviewing files that changed from the base of the PR and between 5e574e0 and 7c952bb.

📒 Files selected for processing (1)

docs/content/docs/authz/custom-resources.mdx

- Note that boot merges permissions already in Postgres (including ones added via CreatePermission), so a restart does not drop them. - Count the generated targets as five (resource, org, project, role binding, role), not four. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Explain that owners and admins get every custom action by default through the generated rules, while other roles get nothing until granted. Show config for both adding an action to a built-in role (which replaces its permission set) and making a new custom role. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

- State that custom actions never need listing on admin roles, since app_project_administer / app_organization_administer already grant them through the schema. - Remove the non-existent "Project Member" role; predefined project roles are Owner, Manager, Viewer only. - Link mentions of the generated rules to the "What rules get generated" section. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

- Org roles are titled Owner / Admin / Member (not "Org Owner" etc.); keep the internal slug in brackets to tell them apart from the project roles. - Rename the example list action to listcomputemachines (plural). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

The role-inheritance (list-vs-get) section was removed, so the title no longer fit. The article is about loading custom resources, the generated permission rules, and which roles get which actions. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Address review feedback on the custom resources doc: - Proxy namespace: state that the name is a free choice. The generator mirrors every custom permission onto app/project and app/organization regardless of namespace, so there is no convention to follow. user/project is just the example. - Admin roles: use the titles and names from PredefinedRoles everywhere, so Owner (app_organization_owner), Admin (app_organization_manager), Project Owner (app_project_owner), and platform admin are no longer ambiguous. - Built-in role permissions: clarify that "already had" means the predefined role defaults, not the base schema. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

coderabbitai

♻️ Duplicate comments (1)

docs/content/docs/authz/custom-resources.mdx (1)
384-385: 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

Stale duplicate wording in Quick Reference contradicts the proxy explanation.

Line 385 still reads "project-level actions (create, list) live on user/project and are checked against the project." A past review flagged this exact phrasing (previously at old line 279 in the "Rule of thumb" section) as misleading, since user/project is only the config-time authoring namespace — the generator mirrors the permission onto app/project, which is where the check actually runs. That earlier occurrence was corrected (now Lines 268-276), but this duplicate copy in the closing Quick Reference summary was missed and still contains the unfixed wording.
Suggested fix
 - Per-item actions (`get`, `update`, `delete`) live on the resource namespace; project-level
-  actions (`create`, `list`) live on `user/project` and are checked against the project.
+  actions (`create`, `list`) are defined under `user/project`, then mirrored onto
+  `app/project`, where the checks actually run.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 41b71f98-e392-4cae-8ae2-55a90ca8afba

📥 Commits

Reviewing files that changed from the base of the PR and between 7c952bb and dfed074.

📒 Files selected for processing (1)

docs/content/docs/authz/custom-resources.mdx

whoAbhishekSah and others added 2 commits June 29, 2026 15:43

vercel Bot deployed to Preview June 30, 2026 04:16 View deployment

coderabbitai Bot reviewed Jun 30, 2026

View reviewed changes

Comment thread docs/content/docs/authz/custom-resources.mdx

Comment thread docs/content/docs/authz/custom-resources.mdx Outdated

vercel Bot deployed to Preview June 30, 2026 04:21 View deployment

coderabbitai Bot reviewed Jun 30, 2026

View reviewed changes

Comment thread docs/content/docs/authz/custom-resources.mdx

whoAbhishekSah and others added 2 commits June 30, 2026 10:00

docs(authz): soften tone of the app/project reference note

96c9036

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

vercel Bot deployed to Preview June 30, 2026 04:31 View deployment

vercel Bot deployed to Preview June 30, 2026 04:40 View deployment

vercel Bot deployed to Preview June 30, 2026 04:46 View deployment

docs(authz): show role title and internal slug together

89cc912

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

vercel Bot deployed to Preview June 30, 2026 04:48 View deployment

vercel Bot deployed to Preview June 30, 2026 04:52 View deployment

vercel Bot deployed to Preview June 30, 2026 04:53 View deployment

whoAbhishekSah requested a review from rohilsurana June 30, 2026 09:16

rohilsurana requested a review from AmanGIT07 July 3, 2026 11:18

AmanGIT07 reviewed Jul 6, 2026

View reviewed changes

Comment thread docs/content/docs/authz/custom-resources.mdx

AmanGIT07 reviewed Jul 6, 2026

View reviewed changes

Comment thread docs/content/docs/authz/custom-resources.mdx Outdated

AmanGIT07 reviewed Jul 6, 2026

View reviewed changes

Comment thread docs/content/docs/authz/custom-resources.mdx Outdated

AmanGIT07 reviewed Jul 6, 2026

View reviewed changes

Comment thread docs/content/docs/authz/custom-resources.mdx Outdated

vercel Bot deployed to Preview July 6, 2026 08:09 View deployment

coderabbitai Bot reviewed Jul 6, 2026

View reviewed changes

AmanGIT07 approved these changes Jul 6, 2026

View reviewed changes

Merge branch 'main' into docs-custom-resource-authz

6efbff2

vercel Bot deployed to Preview July 6, 2026 08:15 View deployment

whoAbhishekSah merged commit bcc6d4c into main Jul 6, 2026
8 checks passed

whoAbhishekSah deleted the docs-custom-resource-authz branch July 6, 2026 08:26

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(authz): custom resource loading and role inheritance#1713

docs(authz): custom resource loading and role inheritance#1713
whoAbhishekSah merged 12 commits into
mainfrom
docs-custom-resource-authz

whoAbhishekSah commented Jun 30, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Jun 30, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jun 30, 2026 •

edited

Loading

Summary by CodeRabbit

Walkthrough

Changes

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

coveralls commented Jun 30, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

whoAbhishekSah commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Notes

Uh oh!

vercel Bot commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Walkthrough

Changes

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

coveralls commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage Report for CI Build 28777571430

Coverage remained the same at 44.865%

Details

Uncovered Changes

Coverage Regressions

Coverage Stats

💛 - Coveralls

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

whoAbhishekSah commented Jun 30, 2026 •

edited

Loading

vercel Bot commented Jun 30, 2026 •

edited

Loading

coderabbitai Bot commented Jun 30, 2026 •

edited

Loading

coveralls commented Jun 30, 2026 •

edited

Loading