Export KetoError from the plugin barrel, and delete a group's grants and parent memberships when its last member leaves #248

Merged
lilleman merged 7 commits from item-65 into main 2026-11-17 01:29:43 +01:00
9 changed files with 203 additions and 55 deletions
+15 -2
View File
@@ -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
+17
View File
@@ -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
+55 -21
View File
@@ -1,8 +1,9 @@
// Groups admin screen: list / create / delete Keto groups and manage membership.
// A group is a Keto subject set `Group:<name>#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<string>(); // 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}` };
});
@@ -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",
@@ -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",
+106
View File
@@ -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>): 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) => {
+7
View File
@@ -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);
});
+1
View File
@@ -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";
-32
View File
@@ -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:<name>#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:<parent>#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