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
- Permission names are authored in plugin code; only grants live in Keto
- 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
- `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`
+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
`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
**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-…` |
| **Group** | Keto | who — a reusable set | `Group:support` |
| **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
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` ⊇
`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
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 }
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");
…
}
+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
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
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
// live Keto check (e.g. sharing/delegation). Permits nest: owner ⊇ editor ⊇ viewer.
// 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 {
related: {
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;
// 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(
keto: KetoClient,
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) => {
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 = {
apiVersion: "1.0.0",
id: "guarded",
routes: [
{ 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: 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: "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 |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 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 |
| 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 |
| 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
@@ -26,16 +25,6 @@
## 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`.
`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
beats hashing the payload), the window, where the record lives given the host is stateless, and how
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.