diff --git a/CHANGELOG.md b/CHANGELOG.md index 37ed0ef..2ee4a19 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,12 @@ The host's contract version is now 0.5.0, so discovery refuses a plugin whose `a `0.4.x`. Change the literal in each plugin's manifest when you upgrade, and add `assetHref` to any `RequestContext` your tests build by hand: `assetHref: (href) => href`. +### `@plainpages/plugin-api` exports `KetoError` + +A plugin that calls `ctx.system.keto` can tell a Keto failure from any other error with +`instanceof KetoError`, as it already can a `KratosError` or a `HydraError`. The error carries the HTTP +`status`. It adds to the plugin API, so an installed plugin needs no change. + ### The core dashboard view is `dashboard`, not `index` `views/index.ejs` is now `views/dashboard.ejs`. The `apiVersion` check can't see this: a plugin view @@ -34,8 +40,15 @@ and answers with the error page. It used to leave some grants gone and the membe Deleting a group now also removes it from every group it was a member of, in the same Keto transaction as the rest. It used to stay listed there, so a group re-created with the same name was -back in every parent. A parent whose only member was the deleted group is left with no members, and -so no longer exists as a group. +back in every parent. + +### The admin example removes a group's grants and parent memberships when its last member leaves + +A group with no members no longer exists, and now neither do its grants or its memberships in other +groups. This holds when the last member is removed, and the group page then says so. It also holds +when deleting a group leaves its parent with no members, and so on up through each ancestor left +empty. A group re-created with the same name used to get the old group's permissions and parents back. +Groups already left empty by an earlier version keep theirs, and re-creating one still restores them. ### The admin example keeps a user's permissions section when it refuses a self-deactivate or self-delete diff --git a/docs/reading-cost.md b/docs/reading-cost.md index ad60726..8e6fddb 100644 --- a/docs/reading-cost.md +++ b/docs/reading-cost.md @@ -581,3 +581,20 @@ Read most (opens and searches): - `src/function-limits.test.ts` 2 - `AGENTS.md` 1 - `CHANGELOG.md` 1 + +## Reading cost, chunk f1bfd1c341a4, finished 2026-11-09T00:42:43Z + +84281 new input tokens before the first commit. + +Read most (opens and searches): + +- `todo.md` 9 +- `README.md` 5 +- `examples/plugins/auth-admin/admin-groups.ts` 5 +- `examples/plugins/auth-admin/admin-shared.ts` 5 +- `src/auth/keto-client.ts` 5 +- `AGENTS.md` 3 +- `examples/plugins/auth-admin/admin-users.ts` 3 +- `src/auth/hydra-admin.ts` 3 +- `src/http/app-admin.test.ts` 3 +- `CHANGELOG.md` 2 diff --git a/examples/plugins/auth-admin/admin-groups.ts b/examples/plugins/auth-admin/admin-groups.ts index 4b869fc..420ca37 100644 --- a/examples/plugins/auth-admin/admin-groups.ts +++ b/examples/plugins/auth-admin/admin-groups.ts @@ -1,8 +1,9 @@ // Groups admin screen: list / create / delete Keto groups and manage membership. // A group is a Keto subject set `Group:#members`; a member is a user or a nested group (see -// parseSubject). Writes go only to Keto (README "stateless"). Keto has no "create object" — a group -// exists exactly while it has ≥1 member, so create writes its first-member tuple and delete removes -// every tuple that makes it a group or puts it in another. Pure builders turn tuples + the request URL into view models; below them are thin +// parseSubject). Writes go only to Keto (README "stateless"). Keto has no "create object": a group +// exists exactly while it has ≥1 member, so create writes its first-member tuple, and removing the +// last member deletes the group (see `withEmptiedGroups`). +// Pure builders turn tuples + the request URL into view models; below them are thin // per-route handlers (keyed on ctx.params) over a shared `withGroups` gate — admin-only, CSRF-guarded, // each returning a RouteResult. @@ -369,7 +370,7 @@ async function groupDetailPage({ ctx, keto, kratosAdmin }: GroupsDeps, name: str // GET /auth-admin/groups/:name — the detail + membership page. export const groupsDetail = withGroupName((deps, name) => - groupDetailPage(deps, name, { notice: grantsNotice(deps.ctx.url, deps.ctx.t) ?? "" })); + groupDetailPage(deps, name, { notice: grantsNotice(deps.ctx.url, deps.ctx.t) ?? emptiedNotice(deps.ctx.url, deps.ctx.t) ?? "" })); // POST /auth-admin/groups/:name/permissions — the submitted checkboxes are the desired set. Members hold // a group's permissions transitively, so the change reaches them at their next login or re-mint — @@ -419,26 +420,56 @@ export const groupsDeleteConfirm = withGroupName(async (deps, name) => { }) }, view: "confirm" }; }, "write"); -// POST /auth-admin/groups/:name/delete — one Keto transaction removes the group's member tuples, -// the tuples naming it as a member of a parent group, and the grants it holds, so a Keto failure -// leaves the group as it was. +const EMPTIED_NOTICE = "group-emptied"; // the `info-msg` that removing a group's last member redirects with +const emptiedNotice = (url: URL, t: Translate): string | undefined => + url.searchParams.get("info-msg") === EMPTIED_NOTICE ? t("admin.groups.emptied") : undefined; + +const tupleId = (t: RelationTuple): string => { + const subject = t.subject_set ? `${t.subject_set.namespace}:${t.subject_set.object}#${t.subject_set.relation}` : t.subject_id; + return `${t.namespace}:${t.object}#${t.relation}@${subject}`; +}; + +// A group exists only through its members. Once `removing` leaves one of `groups` with none, the +// grants on its name and its memberships in other groups must go too, or re-creating the name would +// restore them. Emptying a group can empty its parents, so the walk climbs from each emptied group to +// the groups it is in, and a group left with a member ends that branch. Returns every tuple to delete +// (`removing` and those) and the emptied groups. A member added by another admin between these reads +// and the transaction lands in a stripped group: Keto has no conditional write. +async function withEmptiedGroups(keto: KetoClient, removing: readonly RelationTuple[], groups: readonly string[]): Promise<{ delete: RelationTuple[]; emptied: string[] }> { + const doomed = new Map(removing.map((t) => [tupleId(t), t])); + const pending = [...groups]; + const emptied = new Set(); // also ends the walk on a nesting cycle + for (let group = pending.pop(); group !== undefined; group = pending.pop()) { + if (emptied.has(group)) continue; + const members = await pagedTuples(keto, { namespace: GROUP_NS, object: group, relation: MEMBERS }); + if (members.some((m) => !doomed.has(tupleId(m)))) continue; // may be reached again, by a sibling emptied later + emptied.add(group); + const subject = groupSubject(group); + const grants = (await heldPermissions(keto, subject)).map((permission) => grantTuple(permission, subject)); + const inParents = await pagedTuples(keto, { namespace: GROUP_NS, relation: MEMBERS, ...subject }); + for (const t of [...grants, ...inParents]) doomed.set(tupleId(t), t); + pending.push(...inParents.map((t) => t.object)); + } + return { delete: [...doomed.values()], emptied: [...emptied] }; +} + +// Logged with the groups that lost their grants, since the screen doesn't list them. +function logEmptied(deps: GroupsDeps, event: string, name: string, cascade: { delete: RelationTuple[]; emptied: string[] }): void { + const revoked = new Set(cascade.delete.filter((t) => t.namespace !== GROUP_NS).map((t) => t.object)); + deps.ctx.log.info(event, { actor: deps.user.id, emptied: cascade.emptied.join(","), group: name, revoked: [...revoked].sort().join(",") }); +} + +// POST /auth-admin/groups/:name/delete — one Keto transaction removes the group's member tuples and +// everything `withEmptiedGroups` finds, so a Keto failure leaves the group as it was. export const groupsDelete = withGroupName(async (deps, name) => { - const { ctx, keto, user } = deps; + const { ctx, keto } = deps; await guardedForm(ctx); // CSRF-verify the POST const lost = await lostOnDelete(deps, name); if (lost.length > 0) return refuseSelfLockout(deps, name, "delete", lost); - // A Keto set exists only through its tuples, so leaving the grants or the parents' membership - // tuples behind would resurrect every permission and parent membership the moment someone - // re-created a group with the same name. A parent that had only this group as a member is left - // with none and so ceases to exist, as when its last member is removed by hand; its own grants - // and parent memberships stay (todo.md). - const subject = groupSubject(name); - const held = await heldPermissions(keto, subject); - const grants = held.map((permission) => grantTuple(permission, subject)); const members = await pagedTuples(keto, { namespace: GROUP_NS, object: name, relation: MEMBERS }); - const inParents = await pagedTuples(keto, { namespace: GROUP_NS, relation: MEMBERS, ...subject }); - await keto.transactTuples({ delete: [...grants, ...members, ...inParents], insert: [] }); - ctx.log.info("admin: group deleted", { actor: user.id, group: name, revoked: held.join(",") }); + const cascade = await withEmptiedGroups(keto, members, [name]); + await keto.transactTuples({ delete: cascade.delete, insert: [] }); + logEmptied(deps, "admin: group deleted", name, cascade); return { redirect: ADMIN_GROUPS_BASE }; }); @@ -452,6 +483,9 @@ export const groupsRemoveMember = withGroupName(async (deps, name) => { const removesSelf = tuple.subject_set ? await isMember(keto, user.id, tuple.subject_set.object) : tuple.subject_id === `user:${user.id}`; const lost = removesSelf ? await lostOnLeaving(deps, name) : []; if (lost.length > 0) return refuseSelfLockout(deps, name, "remove", lost); - await keto.deleteTuple(tuple); - return { redirect: detailHref(name) }; + const cascade = await withEmptiedGroups(keto, [tuple], [name]); + await keto.transactTuples({ delete: cascade.delete, insert: [] }); + if (cascade.emptied.length === 0) return { redirect: detailHref(name) }; + logEmptied(deps, "admin: last group member removed", name, cascade); + return { redirect: `${detailHref(name)}?info-msg=${EMPTIED_NOTICE}` }; }); diff --git a/examples/plugins/auth-admin/i18n/en-US.ts b/examples/plugins/auth-admin/i18n/en-US.ts index f9a5b9c..5a14b56 100644 --- a/examples/plugins/auth-admin/i18n/en-US.ts +++ b/examples/plugins/auth-admin/i18n/en-US.ts @@ -71,6 +71,7 @@ const messages = { "admin.groups.create": "Create group", "admin.groups.delete": "Delete group", "admin.groups.deleteMessage": "Delete group {{name}}? This can't be undone.", + "admin.groups.emptied": "That was the last member, so the group no longer exists and its permissions and parent groups are removed.", "admin.groups.error.duplicate": "A group with that name already exists.", "admin.groups.error.selfLockout": "This change would lock you out of {{permissions}}, which you hold through this group. Ask another administrator to make it.", "admin.groups.field.name": "Group name", diff --git a/examples/plugins/auth-admin/i18n/sv-SE.ts b/examples/plugins/auth-admin/i18n/sv-SE.ts index fd4fba0..07bfe93 100644 --- a/examples/plugins/auth-admin/i18n/sv-SE.ts +++ b/examples/plugins/auth-admin/i18n/sv-SE.ts @@ -71,6 +71,7 @@ const messages: AdminMessages = { "admin.groups.create": "Skapa grupp", "admin.groups.delete": "Radera grupp", "admin.groups.deleteMessage": "Ta bort gruppen {{name}}? Det går inte att ångra.", + "admin.groups.emptied": "Det var den sista medlemmen, så gruppen finns inte längre och dess behörigheter och föräldragrupper är borttagna.", "admin.groups.error.duplicate": "Det finns redan en grupp med det namnet.", "admin.groups.error.selfLockout": "Ändringen skulle låsa ute dig från {{permissions}}, som du har genom den här gruppen. Be en annan administratör att göra den.", "admin.groups.field.name": "Gruppnamn", diff --git a/src/http/app-admin.test.ts b/src/http/app-admin.test.ts index 33837e4..04d3474 100644 --- a/src/http/app-admin.test.ts +++ b/src/http/app-admin.test.ts @@ -446,6 +446,112 @@ test("admin group delete: removes the group from every parent, so re-creating th assert.deepEqual(tuples, [member("org", { subject_id: `user:${ada}` }), member("staff", { subject_id: "user:other" })]); }); +// Tuples a group keeps after it loses its last member would be restored by re-creating its name. +const ADA = randomUUID(); +const groupTuple = (object: string, subject: Partial): RelationTuple => ({ namespace: "Group", object, relation: "members", ...subject } as RelationTuple); +const inGroup = (object: string) => ({ subject_set: { namespace: "Group", object, relation: "members" } }); +const grantTo = (group: string, permission = "users:read"): RelationTuple => ({ namespace: "Permission", object: permission, relation: "granted", ...inGroup(group) }); +const groupsAdminHarness = (t: TestContext, tuples: RelationTuple[]) => adminHarness(t, { keto: fakeKeto(tuples), kratosAdmin: stubAdmin({}) }); + +test("admin group delete: a parent left with no members loses its grants and memberships, all the way up", async (t) => { + const tuples: RelationTuple[] = [ + groupTuple("eng", { subject_id: `user:${ADA}` }), + groupTuple("org", inGroup("eng")), grantTo("org"), + groupTuple("company", inGroup("org")), grantTo("company", "users:write"), + groupTuple("everyone", inGroup("company")), groupTuple("everyone", { subject_id: "user:other" }), grantTo("everyone", "groups:read"), + ]; + const { post, token } = await groupsAdminHarness(t, tuples); + + assert.equal((await post("/auth-admin/groups/eng/delete", `_csrf=${token}`)).status, 303); + assert.deepEqual(tuples, [groupTuple("everyone", { subject_id: "user:other" }), grantTo("everyone", "groups:read")]); +}); + +test("admin group delete: a nesting cycle ends the cascade at a group that keeps a member", async (t) => { + const tuples: RelationTuple[] = [ + groupTuple("a", { subject_id: `user:${ADA}` }), groupTuple("a", inGroup("b")), + groupTuple("b", inGroup("a")), grantTo("b"), + groupTuple("c", inGroup("b")), groupTuple("c", { subject_id: "user:other" }), grantTo("c", "groups:read"), + ]; + const { post, token } = await groupsAdminHarness(t, tuples); + + assert.equal((await post("/auth-admin/groups/a/delete", `_csrf=${token}`)).status, 303); + assert.deepEqual(tuples, [groupTuple("c", { subject_id: "user:other" }), grantTo("c", "groups:read")]); +}); + +// The walk reaches `a` a second time, through the cycle, while `p` still waits: it must go on to `p`. +// Keto lists `p@b` before `a@b`, so `a` is popped before `p`. +test("admin group delete: a nesting cycle back to an emptied group doesn't end the cascade", async (t) => { + const tuples: RelationTuple[] = [ + groupTuple("a", { subject_id: `user:${ADA}` }), groupTuple("p", inGroup("b")), groupTuple("a", inGroup("b")), + groupTuple("b", inGroup("a")), grantTo("p"), + ]; + const { post, token } = await groupsAdminHarness(t, tuples); + + assert.equal((await post("/auth-admin/groups/a/delete", `_csrf=${token}`)).status, 303); + assert.deepEqual(tuples, []); +}); + +test("admin group delete: a diamond of nested groups empties the top once both its members are gone", async (t) => { + const tuples: RelationTuple[] = [ + groupTuple("eng", { subject_id: `user:${ADA}` }), + groupTuple("left", inGroup("eng")), groupTuple("right", inGroup("eng")), + groupTuple("top", inGroup("left")), groupTuple("top", inGroup("right")), grantTo("top"), + ]; + const { post, token } = await groupsAdminHarness(t, tuples); + + assert.equal((await post("/auth-admin/groups/eng/delete", `_csrf=${token}`)).status, 303); + assert.deepEqual(tuples, []); +}); + +test("admin group member removal: the last member leaving takes the group's grants and parent memberships with it", async (t) => { + const tuples: RelationTuple[] = [ + groupTuple("eng", { subject_id: `user:${ADA}` }), grantTo("eng"), + groupTuple("org", inGroup("eng")), groupTuple("org", { subject_id: "user:other" }), + groupTuple("solo", inGroup("org")), grantTo("solo", "users:write"), + ]; + const { post, token } = await groupsAdminHarness(t, tuples); + + const res = await post("/auth-admin/groups/eng/members/delete", `_csrf=${token}&member=user:${ADA}`); + assert.equal(res.headers.get("location"), "/auth-admin/groups/eng?info-msg=group-emptied"); + assert.deepEqual(tuples, [groupTuple("org", { subject_id: "user:other" }), groupTuple("solo", inGroup("org")), grantTo("solo", "users:write")]); +}); + +test("admin group member removal: removing someone who isn't a member changes nothing", async (t) => { + const tuples: RelationTuple[] = [groupTuple("eng", { subject_id: `user:${ADA}` }), grantTo("eng")]; + const { post, token } = await groupsAdminHarness(t, tuples); + + const res = await post("/auth-admin/groups/eng/members/delete", `_csrf=${token}&member=user:${randomUUID()}`); + assert.equal(res.headers.get("location"), "/auth-admin/groups/eng"); + assert.equal(tuples.length, 2); +}); + +test("admin group member removal: a group that keeps a member keeps its grants and parents", async (t) => { + const tuples: RelationTuple[] = [groupTuple("eng", { subject_id: `user:${ADA}` }), groupTuple("eng", { subject_id: "user:bob" }), grantTo("eng"), groupTuple("org", inGroup("eng"))]; + const { post, token } = await groupsAdminHarness(t, tuples); + + const res = await post("/auth-admin/groups/eng/members/delete", `_csrf=${token}&member=user:${ADA}`); + assert.equal(res.headers.get("location"), "/auth-admin/groups/eng"); + assert.equal(tuples.length, 3); +}); + +test("admin group member removal: a parent that keeps another nested group keeps its grants", async (t) => { + const tuples: RelationTuple[] = [ + groupTuple("eng", { subject_id: `user:${ADA}` }), + groupTuple("left", inGroup("eng")), groupTuple("right", { subject_id: "user:other" }), + groupTuple("top", inGroup("left")), groupTuple("top", inGroup("right")), grantTo("top"), + ]; + const { post, token } = await groupsAdminHarness(t, tuples); + + await post("/auth-admin/groups/eng/members/delete", `_csrf=${token}&member=user:${ADA}`); + assert.deepEqual(tuples, [groupTuple("right", { subject_id: "user:other" }), groupTuple("top", inGroup("right")), grantTo("top")]); +}); + +test("admin group member removal: the group page shows the notice that the group is gone", async (t) => { + const { get } = await groupsAdminHarness(t, []); + + assert.match(await (await get("/auth-admin/groups/eng?info-msg=group-emptied")).text(), /That was the last member/); +}); + // A double-clicked Save posts twice from one page; the second post finds the first one's result. // A save that changes nothing has nothing to refuse and nothing to revoke. test("admin permission grants: a save that changes nothing is not refused for a stale page and leaves live tokens alone", async (t) => { diff --git a/src/plugin-host/plugin-api.test.ts b/src/plugin-host/plugin-api.test.ts index 7e42cea..f583237 100644 --- a/src/plugin-host/plugin-api.test.ts +++ b/src/plugin-host/plugin-api.test.ts @@ -22,3 +22,10 @@ test("plugin-api re-exports the stable author value surface", () => { assert.equal(api.safeUrl("javascript:alert(1)"), "#"); // the URL sanitiser for rendering untrusted hrefs assert.equal(api.definePlugin({ apiVersion: "1.0.0" }).apiVersion, "1.0.0"); // identity helper works through the barrel }); + +// A plugin matches a Keto failure with `instanceof`, so the barrel must export the class `ctx.system.keto` throws. +test("plugin-api re-exports the KetoError class the Keto client throws", async () => { + const { KetoError } = await import("../auth/keto-client.ts"); + + assert.equal(api.KetoError, KetoError); +}); diff --git a/src/plugin-host/plugin-api.ts b/src/plugin-host/plugin-api.ts index 86cadd7..15c4b75 100644 --- a/src/plugin-host/plugin-api.ts +++ b/src/plugin-host/plugin-api.ts @@ -46,6 +46,7 @@ export type { ExpandTree, KetoClient, RelationQuery, RelationTuple, SubjectSet } export type { HydraAdmin, OAuth2Client } from "../auth/hydra-admin.ts"; export { KratosError } from "../auth/kratos-public.ts"; export { HydraError } from "../auth/hydra-admin.ts"; +export { KetoError } from "../auth/keto-client.ts"; // Sanitise an untrusted URL (upstream/user data) before rendering it in an href/src — partials // escape text but not URL schemes, so a `javascript:`/`data:` URL would be live XSS (see docs). export { safeUrl } from "../http/safe-url.ts"; diff --git a/todo.md b/todo.md index 42d20d8..3687352 100644 --- a/todo.md +++ b/todo.md @@ -12,8 +12,6 @@ | ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score | |---|---|---|---|---|---|---|---|---|---|---|---| -| 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 | | 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 | @@ -26,36 +24,6 @@ ## Details -### 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/auth/keto-client.ts:43`), though `ctx.system.keto` throws it. The barrel is the contract -surface, so this adds to the plugin API: it ships in a minor, and `HOST_API_VERSION` must read -`0.6.0` when 0.6.0 is tagged (AGENTS.md → Rules). Adding is safe for installed plugins; removing it -later would take a major. - -### 72. 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. - -In `examples/plugins/auth-admin/admin-groups.ts` a group exists exactly while it has a -`Group:#members` tuple. Two paths empty a group but keep its other tuples, so re-creating the -name silently hands every new member the old permissions and parent memberships: - -1. `groupsDelete` of a group that is a parent's only member: the parent ceases to exist but keeps - its `Permission:*#granted@Group:#members` grants and its memberships in grandparents. -2. `groupsRemoveMember` removing a group's last member, which today is a lone `deleteTuple`. - -Fix both in one `transactTuples` with the removal: when the removal leaves a group with no members, -add its grants and the tuples naming it as a member of other groups to the delete. The cascade is -transitive: a grandparent emptied by its parent vanishing is the same bug one level up. The walk -stops at a group that keeps any member, so a nesting cycle (`groupsAddMember` refuses only a -self-nest) ends it. An emptied group grants nobody, so the cascade cannot change what -`lostToSelf` computes. Test it with nesting two levels deep and with a cycle. - -When it ships, rewrite the comment at `groupsDelete` that points here, and the CHANGELOG entry "The -admin example removes a deleted group from the groups it was nested in", which then says a parent -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