Align the authorization vocabulary: User, Group, Permission #43

2026-08-03T11:39:45+02:00

lilleman commented

2026-08-03 11:39:45 +02:00

Aligns the authorization vocabulary and documents the model. Supersedes #40, whose commits are included here.

The model is now Identity → Group → Permission.

Identity (was our User) matches Kratos, which owns that record. Keto subjects are identity:<kratos-id>. It collided with the Identity DTO #plugin-api re-exports from kratos-admin.ts — that one is the full Kratos record and keeps the plain name; ours is the JWT projection, now SessionIdentity, reached as ctx.identity.
Permission (was Role) follows RBAC: a permission is one operation ("read shifts"), a role is a bundle of them. A route gates on one operation, so it gates on a permission; a bundle is just a group with several grants, and groups nest. There is no Role namespace. The Keto relation is granted (Permission:x#granted@identity:y); Group keeps members.
Group unchanged. Resource unchanged — the separate per-row tier, and the only place Ory's own sense of "permission" (permits: view/edit/delete) applies.

Manifest surface: route.permission, navNode.permission, permissions: [{ name, description }], PermissionDecl. JWT claim and ctx field are permissions. HOST_API_VERSION stays 1.0.0 — unreleased, no plugin authors to break. No data migration: keto-migrate runs Keto's own bundled schema migrations and our tuples are runtime data, so docker compose down -v covers it.

UI labels stay in ordinary words — the admin menu says "Users", not "Identities", per Nielsen's heuristic #2. Not a rename of an Ory concept: Ory's docs state it uses "identity" interchangeably with "users"/"accounts". Same split as chrome.user/ShellUser (avatar view-model) vs SessionIdentity (entity). Recorded in AGENTS.md so it is not re-litigated.

README gains ## Identities, groups & permissions before Building plugins, since a manifest's permission: gate is unreadable without the model: entity table, a worked graph over three people, a per-route can/cannot walkthrough, the trap that a per-row Resource grant never widens a coarse gate, and the point that Keto ships no namespaces at all — all four are ours.

The Security model section is cut 70 → 36 lines. Its threat table restated code readable at its source (alg allowlist, frame-ancestors, nosniff, localPath, ORY_TIMEOUT_SEC) or duplicated the config table. What remains is only what a deployment gets wrong without it: the private network as the sole guard on the Ory APIs, signed-not-encrypted claims, the 30-day Kratos session behind the ~10m JWT, and non-instant offboarding. The CSRF opt-in footgun moved next to ctx.verifyCsrf.

Aligns the authorization vocabulary and documents the model. Supersedes #40, whose commits are included here. **The model is now `Identity → Group → Permission`.** - **`Identity`** (was our `User`) matches Kratos, which owns that record. Keto subjects are `identity:<kratos-id>`. It collided with the `Identity` DTO `#plugin-api` re-exports from `kratos-admin.ts` — that one is the full Kratos record and keeps the plain name; ours is the JWT projection, now `SessionIdentity`, reached as `ctx.identity`. - **`Permission`** (was `Role`) follows RBAC: a permission is one operation ("read shifts"), a role is a *bundle* of them. A route gates on one operation, so it gates on a permission; a bundle is just a group with several grants, and groups nest. There is no `Role` namespace. The Keto relation is `granted` (`Permission:x#granted@identity:y`); Group keeps `members`. - **`Group`** unchanged. **`Resource`** unchanged — the separate per-row tier, and the only place Ory's own sense of "permission" (`permits`: view/edit/delete) applies. Manifest surface: `route.permission`, `navNode.permission`, `permissions: [{ name, description }]`, `PermissionDecl`. JWT claim and `ctx` field are `permissions`. `HOST_API_VERSION` stays 1.0.0 — unreleased, no plugin authors to break. No data migration: `keto-migrate` runs Keto's own bundled schema migrations and our tuples are runtime data, so `docker compose down -v` covers it. **UI labels stay in ordinary words** — the admin menu says "Users", not "Identities", per Nielsen's heuristic #2. Not a rename of an Ory concept: Ory's docs state it uses "identity" interchangeably with "users"/"accounts". Same split as `chrome.user`/`ShellUser` (avatar view-model) vs `SessionIdentity` (entity). Recorded in AGENTS.md so it is not re-litigated. **README gains `## Identities, groups & permissions`** before Building plugins, since a manifest's `permission:` gate is unreadable without the model: entity table, a worked graph over three people, a per-route can/cannot walkthrough, the trap that a per-row `Resource` grant never widens a coarse gate, and the point that Keto ships no namespaces at all — all four are ours. **The Security model section is cut 70 → 36 lines.** Its threat table restated code readable at its source (alg allowlist, `frame-ancestors`, `nosniff`, `localPath`, `ORY_TIMEOUT_SEC`) or duplicated the config table. What remains is only what a deployment gets wrong without it: the private network as the sole guard on the Ory APIs, signed-not-encrypted claims, the 30-day Kratos session behind the ~10m JWT, and non-instant offboarding. The CSRF opt-in footgun moved next to `ctx.verifyCsrf`.

lilleman changed title from ~~Rename the plugin permission gate to role and document the model~~ to Align the authorization vocabulary with Ory: permission→role, User→Identity

2026-08-03 12:19:13 +02:00

lilleman changed title from ~~Align the authorization vocabulary with Ory: permission→role, User→Identity~~ to Align the authorization vocabulary: Identity, Group, Permission

2026-08-03 17:04:19 +02:00

lilleman changed title from ~~Align the authorization vocabulary: Identity, Group, Permission~~ to Align the authorization vocabulary: User, Group, Permission

2026-08-03 17:16:09 +02:00

lilleman added 14 commits 2026-08-03 17:42:01 +02:00

Document the auth security model in README eb5aafdfaa

Review fixes: re-mint path, real session lifetime, full secret checklist a2204782fa

Review fixes: denylist-conditional revoke, Ory secret wiring, exp guard test 5a5803b265

Add the seeded admin login to the production secrets checklist 73a78d4404

Record the open CSRF token-binding decision as a todo item 4b4ac178ab

Reflow the security-model prose to the file's wrap width f0662cbd0f

Rename the plugin-API permission gate to role b580f7d06e

Document the users, groups and roles model in README 8f9f79ac30

Rename the Keto User namespace to Identity, matching Kratos 3486e0ad00

Cut the security-model threat table down to what the code cannot show 04fe5b1e06