feat(portal, permissions): add portal operator URNs by mcstepp · Pull Request #7377 · unkeyed/unkey

mcstepp · 2026-09-09T22:10:12Z

What does this PR do?

Fixes ENG-3149

Portal routes only understood legacy dotted tuples, so when root keys move to URNs all five of them break. This adds portal to the URN catalog and makes it actually work.

portals.project_id, new and non-nullable. A portal's canonical name is projects/{project_id}/portals/{portal_id}, so it needs a project. Always the project of the app or keyspace it maps to.
All five routes accept either vocabulary, URN or legacy tuple, until callers migrate.
Session minting is now root-key only. Dashboard tokens used to be refused by accident, because the two permission vocabularies never met. Now that stage 1 evaluates URNs, the admin role's workspace-wide grant covers the session URN, so the credential check is the only thing left. A dashboard admin who could mint would get a URL that authenticates as any end user, which is the impersonation dashboard feature we have deferred.

Decisions

Project-wide grants now reach portals, including session minting, because Covers strips a trailing double wildcard and prefix-matches. Nothing had to name portals for that. No root key carries a URN today, so this only affects grants the migration creates.

Cross-project re-points now 412. A portal's URN names its project, so changing it would move the portal under a different set of grants while keeping its id. Not an edge case: keyspaces land in the default project and apps take a named one, so app to keyspace re-points nearly always cross.

WorkOS Dashboard developer and viewer roles gained portal permissions. Before this, only admin could manage portals, via a hardcoded *# string. Added projects/*/portals/* read/write/delete to developer and read to viewer. Can easily change this if we want to refine dashboard permissions a bit more.

Type of change

Bug fix (non-breaking change which fixes an issue)
Chore (refactoring code, technical debt, workflow improvements)
Enhancement (small improvements)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
This change requires a documentation update

How should this be tested?

All automated. The suites that matter:

mise exec -- rask ./svc/api/routes/v2_portal_create_session  # the credential restriction
mise exec -- rask ./pkg/rbac                                 # the legacy to URN translation
mise exec -- rask ./pkg/auth/workos                          # roles manage portals, don't mint
mise exec -- rask ./svc/api/internal/portal                  # project resolution

Tests that encode a decision rather than just coverage:

TestCreateSessionRefusesDashboardTokens and TestDashboardTokensStillManagePortals
TestProjectWideGrantsDeliberatelyReachPortals
TestCreateSessionCeilingInheritsRerollURNWeakness, a weakness inherited from the reroll route, which maps its create and encryption arms to the same canonical key-write leaf. Mirroring it is intentional: a stricter ceiling would refuse mints the operator endpoint allows.
412_test.go, the cross-project refusal

Checklist

Required

Appreciated

Updated the Unkey Docs if changes were necessary

linear-code · 2026-09-09T22:10:15Z

ENG-3149

mintlify · 2026-09-09T22:10:15Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
engineering	🟢 Ready	View Preview	Sep 11, 2026, 4:37 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

vercel · 2026-09-09T22:10:18Z

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

Project	Deployment	Actions	Updated
dashboard	Ready	Preview	Sep 11, 2026 4:40pm UTC
design	Ready	Preview	Sep 11, 2026 4:40pm UTC

chronark · 2026-09-11T05:14:35Z

-// from.
-func seedAppWithKeyspaces(t *testing.T, h *testutil.Harness, workspaceID, slugBase string, keyspaceIDs []string) seededApp {
+// appMapping addresses a portal at an app rather than a keyspace.
+func appMapping(appID string) portal.Mapping {


nit: this util doesn't save LOCs and just adds abstractions, should we remove it?

it's to save width, not lines. i copied it from keyspaceMapping in the other portal tests, but that seeds an actual api and this one is just a struct literal with a name on it. if that's the part that's weird to you, I'll inline it instead

chronark · 2026-09-11T05:28:06Z

+// This is the only control standing between a dashboard token and minting: the
+// WorkOS admin role grants unkey:v1:{workspace}:**#*, which covers the portal
+// session URN stage 1 evaluates, so without this any workspace admin could mint
+// a session authenticating as an arbitrary end user. Naming every enum member
+// keeps a future credential type failing the exhaustive linter until someone
+// decides whether it may mint.


couldn't a workspace admin also create a root key with the required permissions and just mint sessions?

what does this protect against?

yes, an admin can make a root key with the permission and mint with it. this isn't trying to stop that.

what it stops is the browser credential being a mint credential. a dashboard JWT is just sitting in the tab, so without this an XSS on the dashboard mints impersonation URLs for any end user immediately and leaves nothing behind. with it you have to create a root key first, which is deliberate and audit logged.

we're being very explicit about only a root key can be used to mint a session because minting from the dashboard is what we're calling "impersonation."

chronark · 2026-09-11T05:28:59Z

+// CanonicalScopeQueries returns the canonical form of the requirement
+// [ScopeQueries] expresses in legacy tuples, for one scope on one keyspace.
+//
+// The ok flag is load-bearing: rbac.And over zero children evaluates to valid,


The ok flag is load-bearing

:panic-intensifies:

ok but jokes aside, I have no idea what this entire comment is trying to tell me

is it a question about the comment itself, or the intent of the comment?

because what it means is that rbac.And with no children returns true. it looks through the children for a failure, doesn't find one, passes (pkg/rbac/rbac.go:88).

So if I drop the ok flag and always add the URN check, a scope that has no URN form adds an empty And to the Or. that passes, so the whole check for that keyspace passes, and the caller needs no permission at all.

"load bearing" is just saying "don't delete this, it looks pointless and isn't."

mintlify Bot deployed to staging - docs/engineering September 9, 2026 22:10 View deployment

mcstepp force-pushed the eng-3149-finish-portal-urn-permissions-before-the-root-key-migration branch from 44b35df to ebb0129 Compare September 10, 2026 18:34

mintlify Bot deployed to staging - docs/engineering September 10, 2026 18:35 View deployment

vercel Bot deployed to Preview – design September 10, 2026 18:36 View deployment

vercel Bot deployed to Preview – dashboard September 10, 2026 18:38 View deployment

mcstepp marked this pull request as ready for review September 10, 2026 18:41

mcstepp requested review from Flo4604, chronark and ogzhanolguncu September 10, 2026 18:41

vercel Bot deployed to Preview – design September 10, 2026 18:42 View deployment

vercel Bot deployed to Preview – dashboard September 10, 2026 18:44 View deployment

vercel Bot deployed to Preview – design September 10, 2026 19:08 View deployment

vercel Bot deployed to Preview – dashboard September 10, 2026 19:10 View deployment

mcstepp commented Sep 10, 2026

View reviewed changes

Comment thread web/internal/db/src/schema/logdrains.ts

chronark requested changes Sep 11, 2026

View reviewed changes

mcstepp added 12 commits September 11, 2026 12:07

feat(urn): register portal and portal session resource paths

fac9e87

refactor(api): resolve a portal mapping's owning project

5ab2c71

test(portal): seed portal rows through the shared helper

97412e1

feat(portal): store the owning project on each portal row

b60be79

feat(portal): authorize portal management with canonical URNs

4ada49e

feat(portal): mint sessions by URN, restricted to root keys

7f4d369

feat(portal): mirror operator permissions in the mint ceiling

4d57231

feat(auth): grant dashboard roles portal management, not session minting

2907fdd

test(portal): pin that project-wide grants reach portals

8e2d3b5

docs(auth): document the portal resource branch

038e25a

fix(portal): report a cross-project re-point instead of masking it

6fc9f1f

docs(seed): tie the seeded portal's project to its keyspace

206d5ab

mcstepp added 3 commits September 11, 2026 12:07

test(portal): drop the app default branch field removed on main

cc625c8

docs(portal): trim comments to the current standard

485c0ce

refactor(portal): address review feedback on the session mint path

fb64959

mcstepp force-pushed the eng-3149-finish-portal-urn-permissions-before-the-root-key-migration branch from b32e013 to fb64959 Compare September 11, 2026 16:36

mintlify Bot deployed to staging - docs/engineering September 11, 2026 16:37 View deployment

vercel Bot deployed to Preview – dashboard September 11, 2026 16:39 View deployment

vercel Bot deployed to Preview – design September 11, 2026 16:40 View deployment

mcstepp requested a review from chronark September 11, 2026 20:03

Flo4604 approved these changes Sep 11, 2026

View reviewed changes

Navigation Menu

Uh oh!

feat(portal, permissions): add portal operator URNs - #7377

feat(portal, permissions): add portal operator URNs #7377
mcstepp wants to merge 15 commits into
mainfrom
eng-3149-finish-portal-urn-permissions-before-the-root-key-migration

mcstepp commented Sep 9, 2026 •

edited

Loading

Uh oh!

linear-code Bot commented Sep 9, 2026

Uh oh!

mintlify Bot commented Sep 9, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Sep 9, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

chronark Sep 11, 2026

Uh oh!

mcstepp Sep 11, 2026

Uh oh!

Uh oh!

chronark Sep 11, 2026

Uh oh!

mcstepp Sep 11, 2026

Uh oh!

chronark Sep 11, 2026

Uh oh!

chronark Sep 11, 2026

Uh oh!

mcstepp Sep 11, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

mcstepp commented Sep 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

Decisions

Type of change

How should this be tested?

Checklist

Required

Appreciated

Uh oh!

linear-code Bot commented Sep 9, 2026

Uh oh!

mintlify Bot commented Sep 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chronark Sep 11, 2026

Choose a reason for hiding this comment

Uh oh!

mcstepp Sep 11, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

chronark Sep 11, 2026

Choose a reason for hiding this comment

Uh oh!

mcstepp Sep 11, 2026

Choose a reason for hiding this comment

Uh oh!

chronark Sep 11, 2026

Choose a reason for hiding this comment

Uh oh!

chronark Sep 11, 2026

Choose a reason for hiding this comment

Uh oh!

mcstepp Sep 11, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mcstepp commented Sep 9, 2026 •

edited

Loading

mintlify Bot commented Sep 9, 2026 •

edited

Loading

vercel Bot commented Sep 9, 2026 •

edited

Loading