Keep one shared Keto Resource namespace, document the <resource>:<row-id> object name, fix the README per-row example
CI / full-gate (push) Successful in 4m30s

This commit is contained in:
2026-11-17 00:22:03 +01:00
parent be8f198b00
commit 7e8bdd9c39
8 changed files with 43 additions and 17 deletions
+1
View File
@@ -98,6 +98,7 @@ on; a review honours them.
- A permission name is always `<resource>:<action>`, enforced at discovery - A permission name is always `<resource>:<action>`, enforced at discovery
- Permission names are authored in plugin code; only grants live in Keto - Permission names are authored in plugin code; only grants live in Keto
- A permission's `<resource>` is global, not plugin-scoped - A permission's `<resource>` is global, not plugin-scoped
- The `Resource` namespace is shared by all plugins, and an object is `<resource>:<row-id>`
- Declaring a permission stays optional - Declaring a permission stays optional
- `ADMIN_PERMISSIONS` defaults to empty, and an unusable value is dropped with a warning - `ADMIN_PERMISSIONS` defaults to empty, and an unusable value is dropped with a warning
- `actionForMethod` is plugin-local and stays out of `@plainpages/plugin-api` - `actionForMethod` is plugin-local and stays out of `@plainpages/plugin-api`
+7
View File
@@ -263,6 +263,13 @@ proxy in front of Plainpages can't store a signed-in page and serve it to the ne
whose page is the same for everyone can still set its own `cache-control` through whose page is the same for everyone can still set its own `cache-control` through
`RouteResult.headers`; assets are unchanged. `RouteResult.headers`; assets are unchanged.
### A per-row Keto grant names its object `<resource>:<row-id>`
`Resource` is one namespace shared by every plugin, so a bare row id (`4471`) lets two plugins' rows
share one grant. Name the object `shift:4471`, with the same `<resource>` word as your permissions.
Nothing checks this. The README's per-row example now does, and checks the `edit` permit, not the
`editors` relation, so an owner passes.
## 0.4.0 ## 0.4.0
**Breaking.** Set `apiVersion: "0.4.0"`. The app shell no longer bounds the content column, so a page **Breaking.** Set `apiVersion: "0.4.0"`. The app shell no longer bounds the content column, so a page
+11 -2
View File
@@ -249,7 +249,7 @@ Keto relation tuples: `Permission:<name>#granted@user:<id>`, or `@Group:<name>#m
| **User** | Kratos | who you are | `user:0198f2c1-…` | | **User** | Kratos | who you are | `user:0198f2c1-…` |
| **Group** | Keto | who — a reusable set | `Group:support` | | **Group** | Keto | who — a reusable set | `Group:support` |
| **Permission** | Keto | what you may do | `Permission:scheduling:read` | | **Permission** | Keto | what you may do | `Permission:scheduling:read` |
| **Resource** | Keto | which specific row | `Resource:shift-4471` | | **Resource** | Keto | which specific row | `Resource:shift:4471` |
Keto's whole model is one primitive — `namespace:object#relation@subject` — so those four Keto's whole model is one primitive — `namespace:object#relation@subject` — so those four
namespaces are *ours*, declared in `ory/keto/namespaces.keto.ts`; Keto resolves them, transitively namespaces are *ours*, declared in `ory/keto/namespaces.keto.ts`; Keto resolves them, transitively
@@ -359,6 +359,15 @@ The `Resource` namespace covers what a coarse permission cannot express: *this*
*this* person. A `Resource` carries Keto `permits` (`view`, `edit`, `delete`, nesting as `owner` ⊇ *this* person. A `Resource` carries Keto `permits` (`view`, `edit`, `delete`, nesting as `owner` ⊇
`editor` ⊇ `viewer`) and never appears in the JWT. `editor` ⊇ `viewer`) and never appears in the JWT.
> **Warning: name the object `<resource>:<row-id>`, never the bare row id.** `Resource` is one
> namespace shared by every plugin, and Keto stores the object as an opaque string. Two plugins that
> each have a row `4471` and both write `object: "4471"` share one grant: whoever may edit shift
> 4471 may edit invoice 4471. Prefix every object with the same `<resource>` word your permissions
> use (`shift:4471`, `invoice:4471`). Nothing checks this, at boot or at runtime. Check a *permit*
> (`view`, `edit`, `delete`), not a stored relation (`owners`, `editors`, `viewers`), so an owner
> passes an `edit` check. A plugin that needs relations `Resource` can't express adds its own class
> to `ory/keto/namespaces.keto.ts`.
**A per-row grant never widens a coarse gate** — the route's `permission` is checked before the **A per-row grant never widens a coarse gate** — the route's `permission` is checked before the
handler runs. Gate the route on something they hold, then narrow inside the handler: handler runs. Gate the route on something they hold, then narrow inside the handler:
@@ -366,7 +375,7 @@ handler runs. Gate the route on something they hold, then narrow inside the hand
{ method: "POST", path: "/shifts/:id", permission: READ, handler: editShift } { method: "POST", path: "/shifts/:id", permission: READ, handler: editShift }
async function editShift(ctx) { async function editShift(ctx) {
if (!(await check(keto, ctx, { namespace: "Resource", object: ctx.params.id, relation: "editors" }))) if (!(await check(keto, ctx, { namespace: "Resource", object: `shift:${ctx.params.id}`, relation: "edit" })))
throw new GuardError(403, "not an editor of this shift"); throw new GuardError(403, "not an editor of this shift");
… …
} }
+12
View File
@@ -209,6 +209,18 @@ Hence `oauth2-clients`, not `clients`. Users are the host's, and plugins share t
that collision-freedom is a convention rather than structural; the alternative penalizes the that collision-freedom is a convention rather than structural; the alternative penalizes the
sharing case. sharing case.
## The `Resource` namespace is shared by all plugins, and an object is `<resource>:<row-id>`
2026-11-17, the maintainer. Goal 7. Valid while no plugin needs a relation `Resource` can't express.
Ory's examples use one namespace per domain (`Shift`, `Document`). Splitting here would make an
operator edit `ory/keto/namespaces.keto.ts` for every plugin, so a drop-in stops being drop-in, and
a missing namespace fails on the first request rather than at boot. It also breaks the contract
(a minor) for a tier no shipped code uses. One namespace with the kind in the object follows the
`<resource>` rule above and `Permission:<resource>:<action>`. The cost is that nothing enforces
the prefix, so a bare row id lets two plugins share a grant; the README warns of it. A plugin that
needs its own relations adds a class to the OPL file, which already works. Revisit when one does.
## Declaring a permission stays optional ## Declaring a permission stays optional
2026-08-05, the maintainer. Goal 7. Valid while plugins may share a permission. 2026-08-05, the maintainer. Goal 7. Valid while plugins may share a permission.
+2
View File
@@ -29,6 +29,8 @@ class Permission implements Namespace {
// A fine-grained, relationship-checked resource — README's third "may I?" tier, the rare // A fine-grained, relationship-checked resource — README's third "may I?" tier, the rare
// live Keto check (e.g. sharing/delegation). Permits nest: owner ⊇ editor ⊇ viewer. // live Keto check (e.g. sharing/delegation). Permits nest: owner ⊇ editor ⊇ viewer.
// Grants accept a user directly or any member of a group. // Grants accept a user directly or any member of a group.
// Every plugin shares this namespace, so an object is `<resource>:<row-id>` (`shift:4471`):
// a bare row id lets two plugins' rows share one grant. Nothing enforces that.
class Resource implements Namespace { class Resource implements Namespace {
related: { related: {
owners: (User | SubjectSet<Group, "members">)[] owners: (User | SubjectSet<Group, "members">)[]
+2 -1
View File
@@ -41,7 +41,8 @@ export function can(ctx: RequestContext, permission: string): boolean {
} }
// Live Keto relationship check at the point of action. The subject is the current user; // Live Keto relationship check at the point of action. The subject is the current user;
// anonymous ⇒ false (fail-closed, no Keto call). // anonymous ⇒ false (fail-closed, no Keto call). In the shared `Resource` namespace the object
// is `<resource>:<row-id>`, never a bare id (README → Fine-grained, per-row access).
export async function check( export async function check(
keto: KetoClient, keto: KetoClient,
ctx: RequestContext, ctx: RequestContext,
+2 -2
View File
@@ -268,14 +268,14 @@ test("session re-mint runs only for an expired token with all three Ory clients
}); });
test("guards map to responses: requireSession → /login, a failed can/check → 403, success runs the handler", async (t) => { test("guards map to responses: requireSession → /login, a failed can/check → 403, success runs the handler", async (t) => {
const keto = { check: async (tuple: { object: string }) => tuple.object === "open" } as unknown as Parameters<typeof check>[0]; const keto = { check: async (tuple: { object: string }) => tuple.object === "doc:open" } as unknown as Parameters<typeof check>[0];
const guarded: Plugin = { const guarded: Plugin = {
apiVersion: "1.0.0", apiVersion: "1.0.0",
id: "guarded", id: "guarded",
routes: [ routes: [
{ handler: (ctx) => ({ html: `hi ${requireSession(ctx).email}` }), method: "GET", path: "/me" }, { handler: (ctx) => ({ html: `hi ${requireSession(ctx).email}` }), method: "GET", path: "/me" },
{ handler: (ctx) => { if (!can(ctx, "admin")) throw new GuardError(403, "no"); return { html: "ok" }; }, method: "GET", path: "/admin-only" }, { handler: (ctx) => { if (!can(ctx, "admin")) throw new GuardError(403, "no"); return { html: "ok" }; }, method: "GET", path: "/admin-only" },
{ handler: async (ctx) => { if (!(await check(keto, ctx, { namespace: "Resource", object: ctx.params.id ?? "", relation: "view" }))) throw new GuardError(403, "no"); return { html: "seen" }; }, method: "GET", path: "/doc/:id" }, { handler: async (ctx) => { if (!(await check(keto, ctx, { namespace: "Resource", object: `doc:${ctx.params.id ?? ""}`, relation: "view" }))) throw new GuardError(403, "no"); return { html: "seen" }; }, method: "GET", path: "/doc/:id" },
{ handler: () => ({ html: "gated" }), method: "GET", path: "/gated", permission: "secret:read" }, // declarative route gate { handler: () => ({ html: "gated" }), method: "GET", path: "/gated", permission: "secret:read" }, // declarative route gate
{ handler: () => ({ html: "mine" }), method: "GET", path: "/mine", session: true }, // declarative session gate { handler: () => ({ html: "mine" }), method: "GET", path: "/mine", session: true }, // declarative session gate
], ],
+6 -12
View File
@@ -12,12 +12,11 @@
| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score | | ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
|---|---|---|---|---|---|---|---|---|---|---|---| |---|---|---|---|---|---|---|---|---|---|---|---|
| 19 | 0.6.0 | | question | **Run the documented Docker commands on macOS and fix whatever misbehaves.** | 2 | 2 | 1 | 3 | 3 | 1 by 3 | 3.3 |
| 16 | 0.6.0 | | question | **Decide whether the single Keto `Resource` namespace splits into per-domain namespaces.** | 3 | 2 | 3 | 6 | 6 | 7 by 2 | 0.5 |
| 65 | 0.6.0 | | | **Export `KetoError` from `@plainpages/plugin-api`, so a plugin can tell a Keto failure apart with `instanceof`.** | 1 | 2 | 1 | 2 | 1 | 7 by 3, 1 by 1 | 6.7 | | 65 | 0.6.0 | | | **Export `KetoError` from `@plainpages/plugin-api`, so a plugin can tell a Keto failure apart with `instanceof`.** | 1 | 2 | 1 | 2 | 1 | 7 by 3, 1 by 1 | 6.7 |
| 72 | 0.6.0 | | | **Delete a group's grants and parent memberships when its last member leaves, by group delete or by removing the member, so re-creating the name restores none.** | 2 | 2 | 2 | 4 | 3 | 2 by 4 | 4.2 | | 72 | 0.6.0 | | | **Delete a group's grants and parent memberships when its last member leaves, by group delete or by removing the member, so re-creating the name restores none.** | 2 | 2 | 2 | 4 | 3 | 2 by 4 | 4.2 |
| 67 | 0.6.0 | | | **Group `src/auth`'s modules into one subfolder per concern, with `bootstrap.ts` staying at `src/auth/bootstrap.ts`.** | 3 | 1 | 2 | 4 | 6 | code health by 4 | 4.0 | | 67 | 0.6.0 | | | **Group `src/auth`'s modules into one subfolder per concern, with `bootstrap.ts` staying at `src/auth/bootstrap.ts`.** | 3 | 1 | 2 | 4 | 6 | code health by 4 | 4.0 |
| 14 | 0.6.0 | | | **Drop a double-clicked duplicate submit, with no client-side JavaScript.** | 4 | 2 | 3 | 7 | 7 | 2 by 7, 1 by 4 | 1.4 | | 14 | 0.6.0 | | | **Drop a double-clicked duplicate submit, with no client-side JavaScript.** | 4 | 2 | 3 | 7 | 7 | 2 by 7, 1 by 4 | 1.4 |
| 19 | 0.7.0 | | question | **Run the documented Docker commands on macOS and fix whatever misbehaves.** | 2 | 2 | 1 | 3 | 3 | 1 by 3 | 3.3 |
## Renamed ## Renamed
@@ -26,16 +25,6 @@
## Details ## Details
### 19. Run the documented Docker commands on macOS and fix whatever misbehaves.
Needs a Mac. Two suspects, both from `--user "$(id -u):$(id -g)"`: a macOS `id -g` is `20`, which is
`dialout` inside the noble image, and Docker Desktop remaps bind-mount ownership in its VM.
### 16. Decide whether the single Keto `Resource` namespace splits into per-domain namespaces.
Ory's own examples model `Shift`, `Document` and so on. One global `Resource` bucket is the
project's "no catch-all names" rule applied to namespaces.
### 65. Export `KetoError` from `@plainpages/plugin-api`, so a plugin can tell a Keto failure apart with `instanceof`. ### 65. Export `KetoError` from `@plainpages/plugin-api`, so a plugin can tell a Keto failure apart with `instanceof`.
`src/plugin-host/plugin-api.ts` ~L47-48 exports `KratosError` and `HydraError`, but not `KetoError` `src/plugin-host/plugin-api.ts` ~L47-48 exports `KratosError` and `HydraError`, but not `KetoError`
@@ -86,3 +75,8 @@ host recognising a duplicate (same session, route and payload within a short win
dropping it. Open: what identifies "the same submission" (a one-time token minted into each form dropping it. Open: what identifies "the same submission" (a one-time token minted into each form
beats hashing the payload), the window, where the record lives given the host is stateless, and how beats hashing the payload), the window, where the record lives given the host is stateless, and how
a plugin declares a route repeatable. a plugin declares a route repeatable.
### 19. Run the documented Docker commands on macOS and fix whatever misbehaves.
Needs a Mac. Two suspects, both from `--user "$(id -u):$(id -g)"`: a macOS `id -g` is `20`, which is
`dialout` inside the noble image, and Docker Desktop remaps bind-mount ownership in its VM.