diff --git a/AGENTS.md b/AGENTS.md index 6441922..3bf4da6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -98,6 +98,7 @@ on; a review honours them. - A permission name is always `:`, enforced at discovery - Permission names are authored in plugin code; only grants live in Keto - A permission's `` is global, not plugin-scoped +- The `Resource` namespace is shared by all plugins, and an object is `:` - 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` diff --git a/CHANGELOG.md b/CHANGELOG.md index a630eb8..37ed0ef 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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` 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 `` 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 diff --git a/README.md b/README.md index d46285d..e3cdace 100644 --- a/README.md +++ b/README.md @@ -249,7 +249,7 @@ Keto relation tuples: `Permission:#granted@user:`, or `@Group:#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 `:`, 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 `` 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"); … } diff --git a/docs/comprehension-history.md b/docs/comprehension-history.md index 0a45a44..208fbde 100644 --- a/docs/comprehension-history.md +++ b/docs/comprehension-history.md @@ -600,3 +600,39 @@ Inherited architect, would restructure first: - Locality: `src/http/app.ts:202` `Host`: 19 fields, and a new request capability touches four files - Shape, Self-sufficiency: `examples/plugins/auth-admin/admin-shared.ts:107` `FieldConfig`: the type for a core partial's option shape lives in an example plugin - Locality: `src/auth/login.ts:48` `readPermissions`: a second copy of the Keto paging loop that nothing says the barrel boundary forces + +## 2026-11-16T23:56:01Z, PR #247 at 7e8bdd9 + +| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall | +|---|---|---|---|---|---| +| Junior A | 7.5 | 6.5 | 7 | 6.5 | 7 | +| Mid A | 8 | 7 | 7 | 7 | 7.5 | +| Maintainability senior | 7.5 | 6 | 7 | 7 | 7 | +| Inherited architect | 7 | 7 | 6.5 | 7 | 7 | +| Mean | 7.50 | 6.63 | 6.88 | 6.88 | 7.13 | + +Junior A, hardest first: + +- Locality, Shape, Overall: `src/http/app.ts:67` `createApp`: about 130 lines of closures that refer to each other, `switchBase` reads `builtinRoutes` declared later +- Locality: `src/http/app.ts:263` `prepareRequest`: chrome is memoized lazily twice, and an untyped `shared` bag feeds `buildContext` +- Self-sufficiency: `src/auth/routes.ts:58` `flowFailure`: six branches keyed on Kratos statuses that nothing in the file explains +- Locality: `src/server.ts:25` `delete process.env["PLUGIN_DB_SECRET"]`: a load-bearing order rule in a top-level script + +Mid A, hardest first: + +- Locality, Shape, Overall: `src/http/app.ts:67` `createApp`: about 130 lines, 20 option fields, route table and `switchBase` refer to each other +- Locality: `src/http/app.ts:263` `prepareRequest`: implicit stage order, three ways to get a context +- Self-sufficiency: `src/auth/routes.ts:58` `flowFailure`: the Kratos status meanings are unexplained + +Maintainability senior, hardest first: + +- Locality, Shape, Overall: `src/http/app.ts:67` `createApp`: about 130 lines, a dozen closures calling each other +- Locality: `src/i18n/locale.ts:81` `chosenLocale`: recovers "was a locale requested" from `localeHref("/") === "/"`, so the name hides the mechanism +- Locality: `views/partials/data-table.ejs:74` include: EJS locals leak from page to partial, defended by explicit null options +- Self-sufficiency: `examples/plugins/auth-admin/admin-groups.ts:434` `groupsDelete`: its comment ends with a pointer to `todo.md` + +Inherited architect, would restructure first: + +- Navigation, Shape, Overall: `src/auth/bootstrap.ts:1` `src/auth`: 20 files over four concerns, and `bootstrap.ts` belongs to none of them +- Shape: `public/css/styles.css:81` dark and light palette mapping: the same token list written three times +- Locality: `src/http/app.ts:202` `Host`: restates the options and locals a third time, so a new capability touches several files diff --git a/docs/decisions.md b/docs/decisions.md index 6737914..a7d16f4 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -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 `:` + +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 +`` rule above and `Permission::`. 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. diff --git a/ory/keto/namespaces.keto.ts b/ory/keto/namespaces.keto.ts index deb70d6..ca69512 100644 --- a/ory/keto/namespaces.keto.ts +++ b/ory/keto/namespaces.keto.ts @@ -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 `:` (`shift:4471`): +// a bare row id lets two plugins' rows share one grant. Nothing enforces that. class Resource implements Namespace { related: { owners: (User | SubjectSet)[] diff --git a/src/auth/guards.ts b/src/auth/guards.ts index 5012ee4..a57a3ea 100644 --- a/src/auth/guards.ts +++ b/src/auth/guards.ts @@ -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 `:`, never a bare id (README → Fine-grained, per-row access). export async function check( keto: KetoClient, ctx: RequestContext, diff --git a/src/http/app-plugins.test.ts b/src/http/app-plugins.test.ts index 3f3ee9b..557a7f6 100644 --- a/src/http/app-plugins.test.ts +++ b/src/http/app-plugins.test.ts @@ -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[0]; + const keto = { check: async (tuple: { object: string }) => tuple.object === "doc:open" } as unknown as Parameters[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 ], diff --git a/todo.md b/todo.md index 848f488..42d20d8 100644 --- a/todo.md +++ b/todo.md @@ -6,18 +6,18 @@ `Bar = 1` -`Next ID = 73` +`Next ID = 74` ## Items | 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 | +| 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 | 1.0 | +| 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 | +| 73 | 0.7.0 | | owner | **Reach the comprehension floor: make the request pipeline in `src/http/app.ts` and the locale and EJS-locals plumbing readable one unit at a time, so every dimension mean reaches 7.0.** | 3 | 1 | 2 | 4 | 7 | code health by 7 | 0.9 | ## Renamed @@ -26,16 +26,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` @@ -66,6 +56,16 @@ admin example removes a deleted group from the groups it was nested in", which t left with no members no longer exists as a group. `lostToSelf`, in this file, is a place the seats found hard; if the change touches it, make it easier to read. +### 14. Drop a double-clicked duplicate submit, with no client-side JavaScript. + +A second identical POST is expected from a non-technical user, and today creates two +users, mints two recovery codes, or registers two OAuth2 clients. It must not break a legitimately +repeatable action. Sketch: a CSS-only affordance so the second click has nothing to hit, plus the +host recognising a duplicate (same session, route and payload within a short window), logging and +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. + ### 67. Group `src/auth`'s modules into one subfolder per concern, with `bootstrap.ts` staying at `src/auth/bootstrap.ts`. `src/auth` holds 19 modules over several concerns: the per-request session path (`jwt*`, `jwks`, @@ -77,12 +77,23 @@ name, and update the folder list in `docs/decisions.md` → "`src/` is grouped b barrel, so only `src/plugin-host/plugin-api.ts`'s paths change for them. Update the README file map. Make `src/auth` easier to navigate, a place the seats found hard. -### 14. Drop a double-clicked duplicate submit, with no client-side JavaScript. +### 19. Run the documented Docker commands on macOS and fix whatever misbehaves. -A second identical POST is expected from a non-technical user, and today creates two -users, mints two recovery codes, or registers two OAuth2 clients. It must not break a legitimately -repeatable action. Sketch: a CSS-only affordance so the second click has nothing to hit, plus the -host recognising a duplicate (same session, route and payload within a short window), logging and -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. +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. + +### 73. Reach the comprehension floor: make the request pipeline in `src/http/app.ts` and the locale and EJS-locals plumbing readable one unit at a time, so every dimension mean reaches 7.0. + +The scoring run on PR #247 at 7e8bdd9 gave means Navigation 7.50, Locality 6.63, Shape 6.88, Self-sufficiency 6.88, Overall 7.13. Locality is the lowest. Item 67 covers the `src/auth` folder, so this item leaves it out. + +Places the seats named, to make easier to read: +- `src/http/app.ts:67` `createApp`: about 130 lines of closures that refer to each other, and `switchBase` reads `builtinRoutes`, which is declared later; all four seats named it. +- `src/http/app.ts:263` `prepareRequest` and `src/http/context.ts:97` `buildContext`: chrome is memoized lazily in both, and an untyped `shared` bag feeds the context, so a new context field touches about five declarations. +- `src/http/app.ts:202` `Host`: restates the options and locals a third time. +- `src/i18n/locale.ts:81` `chosenLocale`: recovers "was a locale requested" from `localeHref("/") === "/"`, so its name hides the mechanism. +- `views/partials/data-table.ejs:74`, `views/partials/menu.ejs:22` and `views/partials/filter-bar.ejs:26`: EJS locals leak into includes, defended by explicit null options. +- `src/server.ts:25` `delete process.env["PLUGIN_DB_SECRET"]`: a load-bearing order rule in a top-level script. +- `public/css/styles.css:81`: the dark and light token mapping is written three times. +- `src/auth/routes.ts:58` `flowFailure`: Kratos statuses that no comment in the file explains. + +Aim: a reader of one unit should not need the other units open beside it. Re-run the scoring run when it ships.