Skip to content

feat: show permission guards in the starter templates - #152

Merged
Bccorb merged 4 commits into
mainfrom
feat/starter-permission-guards
Nov 7, 2026
Merged

Bccorb merged 4 commits into
mainfrom
feat/starter-permission-guards

Conversation

@Bccorb

@Bccorb Bccorb commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

Closes #149. Every starter now shows a permission check: the server starters guard a route with their adapter's permission guard, and the UI starters show content only to a holder of the permission.

Merge with the auth API v0.23.0 release, not before. On API v0.22 no token carries permissions, so the new route answers 403 to everyone, and "works out of the box" only holds once v0.23.0 ships (fells-code/seamless-auth-api#566). The comments and READMEs say so.

What

  • One permission everywhere: reports:read. It is the example used in the adapter docs, and with one name a single grant opens both the route and the UI in whichever starters you combine.
  • Server starters serve GET /reports beside /beta_users:
    • Express: requirePermission
    • Fastify: requirePermission as a preHandler
    • Gin: auth.RequirePermission, through a small adapterGuard helper that requireSession now shares
    • Axum: auth.require_permission as a route layer
    • FastAPI: RequireUser(auth, permissions=[...])
    • Next.js: /api/reports with requirePermission
  • UI starters gate content with their SDK's hasPermission:
    • React (Vite and OAuth): a shared ReportsPanel component, from shared/react-app and synced into each
    • Next.js: ReportsAccess on the Beta page
    • Angular, Vue, Svelte and Expo: the beta page, using their published SDK helpers
    • Each says that the server guard is what enforces.
  • Setup steps in each README and AGENTS.md: add a dedicated reportViewer role to available_roles (console system config, or seamless config set available_roles), create reports:read and grant it to reportViewer, through the console's Roles page or POST /admin/permissions and PUT /admin/roles/instance/reportViewer/permissions (both need admin:write and step-up), give your user the role, then sign in again. The Roles page is not in a console release yet, and the READMEs say so.
  • Pins move to the releases that have the guard and helpers:
    • npm: express 0.25, fastify 0.16, nextjs 0.9, react 0.20 (with client 0.9.0), angular 0.5, vue 0.4, svelte 0.4, react-native 0.5
    • Go seamless-auth-go v0.6.0, Rust seamless-auth 0.6, Python seamless-auth[fastapi] 0.6
    • Lock files were regenerated with each tool.
  • Changeset: minor.

Behavior notes

  • Python 0.6.0 is breaking for FastAPI (adapter refusals moved from detail to error). The template never read detail, and its 401 test now asserts {"error":"unauthenticated"}. The template's own require_role still answers {"detail":"forbidden"}, which this leaves alone.
  • The content-type gate needs no change here. It covers /auth routes only, the template routes are GETs, and client 0.9.0 sends the transport header.

For review

  • Unrelated and already there before this PR: the Express README says beta_user where the code uses betaUser.

Testing

  • Root: npm run validate, format:check, sync-shared --check and the pre-commit hook all pass.
  • All 9 npm starters: npm run check and npm run build, on Node 24.
  • Gin: gofmt, go vet and go test.
  • Axum: cargo fmt --check, clippy -D warnings and cargo test --locked.
  • FastAPI: uv sync --locked, ruff, mypy and pytest.
  • Not run:
    • CI's docker build --target runtime for Gin, Axum and FastAPI, and its Node 22 and latest matrix
    • Anything against a live stack. The new server tests cover only the 401 without a session; 403 and 200 need a real token from API v0.23.

Each API starter and the Next.js starter serves GET /reports behind its
adapter's permission guard for reports:read, beside the betaUser role
route. The web and mobile starters show the reports only to a holder of
reports:read, with the server guard as what enforces. READMEs and
AGENTS.md carry the steps to create the permission and grant it to a role,
and say that it needs auth API v0.23: on v0.22 the guard answers 403 to
everyone.

Moves the starters to the adapter and SDK releases that carry the guard
and the client permission helpers.

Closes #149
The starters granted the example permission through the existing betaUser
role. A role of its own keeps the permission example apart from the role
example, so the steps now add reportViewer to available_roles first.
@Bccorb
Bccorb merged commit 566d7b2 into main Nov 7, 2026
4 checks passed
@Bccorb
Bccorb deleted the feat/starter-permission-guards branch November 8, 2026 00:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: show permission guards in the starter templates

1 participant