@simple-auth-kit/cli 1.0.0

package/registry/combos/nestjs-prisma/variants/workspaces/src/workspace.controller.ts

@@ -0,0 +1,111 @@
+import { BadRequestException, Body, Controller, Delete, ForbiddenException, Get, Inject, Param, Post, Put, Req, UseGuards } from "@nestjs/common";
+import { ApiBearerAuth, ApiBody, ApiHeader, ApiOperation, ApiParam, ApiResponse, ApiTags } from "@nestjs/swagger";
+import type { Request } from "express";
+import { AbilityGuard } from "./ability.guard.js";
+import { AuthGuard } from "./auth.guard.js";
+import { WORKSPACE_HEADER, WorkspaceGuard } from "./authz.guard.js";
+import { Authenticated, CheckAbility } from "./route-tiers.js";
+import { OkResponseDto } from "./dto/auth.dto.js";
+import { AddMemberDto, CreateWorkspaceDto, MemberRolesResponseDto, MembershipSummaryDto, SetMemberRolesDto, WorkspaceSummaryDto } from "./dto/workspace.dto.js";
+import { RbacRepository } from "./rbac.repository.js";
+import { WorkspaceRepository } from "./workspace.repository.js";
+
+function requireString(value: unknown, field: string): string {
+  if (typeof value !== "string" || value.length === 0) throw new BadRequestException(`${field} is required`);
+  return value;
+}
+
+function requireStringArray(value: unknown, field: string): string[] {
+  if (!Array.isArray(value) || value.some((v) => typeof v !== "string")) throw new BadRequestException(`${field} must be an array of strings`);
+  return value as string[];
+}
+
+const WORKSPACE_HEADER_DOC = {
+  name: WORKSPACE_HEADER,
+  required: true,
+  description: "The workspace this request acts in. The caller must be a member of it.",
+};
+
+// Every route below that acts *inside* a workspace names it with the `X-Workspace-Id` header
+// rather than a path segment. `POST /workspaces` and `GET /workspaces` are tier 2
+// (`@Authenticated()`, no permission slug) since they're outside any workspace — any
+// authenticated user may create one or list their own. `GET /workspaces/members` is gated on
+// membership itself, proven by `WorkspaceGuard`. The three that mutate membership are
+// permission-gated — see `rbac.defaults.ts` for the catalog.
+@ApiTags("workspaces")
+@Controller("workspaces")
+@ApiBearerAuth()
+export class WorkspaceController {
+  constructor(
+    @Inject(WorkspaceRepository) private readonly workspaces: WorkspaceRepository,
+    @Inject(RbacRepository) private readonly rbac: RbacRepository,
+  ) {}
+
+  @Post()
+  @Authenticated()
+  @UseGuards(AuthGuard)
+  @ApiOperation({ summary: "Create a workspace", description: "The creator becomes its first member, with the admin role." })
+  @ApiBody({ type: CreateWorkspaceDto })
+  @ApiResponse({ status: 201, type: WorkspaceSummaryDto })
+  async create(@Body() body: Record<string, unknown>, @Req() req: Request) {
+    return this.workspaces.create(req.auth!.sub, requireString(body.name, "name"));
+  }
+
+  @Get()
+  @Authenticated()
+  @UseGuards(AuthGuard)
+  @ApiOperation({ summary: "List the workspaces the current user belongs to, with their roles in each" })
+  @ApiResponse({ status: 200, type: [WorkspaceSummaryDto] })
+  async listMine(@Req() req: Request) {
+    return this.workspaces.listForUser(req.auth!.sub);
+  }
+
+  @Get("members")
+  @Authenticated()
+  @UseGuards(AuthGuard, WorkspaceGuard)
+  @ApiHeader(WORKSPACE_HEADER_DOC)
+  @ApiOperation({ summary: "List the members of the named workspace" })
+  @ApiResponse({ status: 200, type: [MembershipSummaryDto] })
+  async listMembers(@Req() req: Request) {
+    return this.workspaces.listMembers(req.authz!.workspaceId);
+  }
+
+  @Post("members")
+  @UseGuards(AuthGuard, WorkspaceGuard, AbilityGuard)
+  @CheckAbility("members:manage")
+  @ApiHeader(WORKSPACE_HEADER_DOC)
+  @ApiOperation({ summary: "[admin] Add an existing user to the named workspace" })
+  @ApiBody({ type: AddMemberDto })
+  @ApiResponse({ status: 201, type: MembershipSummaryDto })
+  async addMember(@Body() body: Record<string, unknown>, @Req() req: Request) {
+    // No `roles` in the body means "whatever this workspace flags as the default role".
+    const roles = body.roles === undefined ? undefined : requireStringArray(body.roles, "roles");
+    return this.workspaces.addMember(req.authz!.workspaceId, requireString(body.email, "email"), roles);
+  }
+
+  @Put("members/:memberId/roles")
+  @UseGuards(AuthGuard, WorkspaceGuard, AbilityGuard)
+  @CheckAbility("roles:assign")
+  @ApiHeader(WORKSPACE_HEADER_DOC)
+  @ApiOperation({ summary: "[admin] Replace a member's roles within the named workspace" })
+  @ApiParam({ name: "memberId" })
+  @ApiBody({ type: SetMemberRolesDto })
+  @ApiResponse({ status: 200, type: MemberRolesResponseDto })
+  async setMemberRoles(@Param("memberId") memberId: string, @Body() body: Record<string, unknown>, @Req() req: Request) {
+    if (memberId === req.authz!.memberId) throw new ForbiddenException("cannot change your own roles");
+    return this.rbac.setMemberRoles(req.authz!.workspaceId, memberId, requireStringArray(body.roles, "roles"));
+  }
+
+  @Delete("members/:memberId")
+  @UseGuards(AuthGuard, WorkspaceGuard, AbilityGuard)
+  @CheckAbility("members:manage")
+  @ApiHeader(WORKSPACE_HEADER_DOC)
+  @ApiOperation({ summary: "[admin] Remove a member from the named workspace", description: "Their direct permission grants go with the membership." })
+  @ApiParam({ name: "memberId" })
+  @ApiResponse({ status: 200, type: OkResponseDto })
+  async removeMember(@Param("memberId") memberId: string, @Req() req: Request) {
+    if (memberId === req.authz!.memberId) throw new ForbiddenException("cannot remove yourself from a workspace you administer");
+    await this.workspaces.removeMember(req.authz!.workspaceId, memberId);
+    return { ok: true };
+  }
+}

package/registry/combos/nestjs-prisma/variants/workspaces/src/workspace.repository.ts

@@ -0,0 +1,177 @@
+import { ConflictException, Inject, Injectable, NotFoundException } from "@nestjs/common";
+import { PrismaClient } from "../generated/prisma/client.js";
+import { provisionDefaultRoles, WORKSPACE_CREATOR_ROLES } from "./rbac.defaults.js";
+import { RbacRepository } from "./rbac.repository.js";
+import { toId } from "./id.helper.js";
+
+export interface WorkspaceSummary {
+  id: string;
+  name: string;
+  createdAt: string;
+  /** The calling user's role slugs in this workspace. */
+  roles: string[];
+}
+
+export interface MembershipSummary {
+  memberId: string;
+  userId: string;
+  email: string;
+  roles: string[];
+  createdAt: string;
+}
+
+@Injectable()
+export class WorkspaceRepository {
+  constructor(
+    @Inject(PrismaClient) private readonly prisma: PrismaClient,
+    @Inject(RbacRepository) private readonly rbac: RbacRepository,
+  ) {}
+
+  // Creates a workspace, its creator's admin membership, and that workspace's default roles all
+  // in one transaction, so a workspace is never left without an administrator. `Role` is unique
+  // per `[workspaceId, slug]`, so a new workspace genuinely has no `Role` rows without this step.
+  async create(userId: string, name: string): Promise<WorkspaceSummary> {
+    const userIdBig = toId(userId);
+    const workspace = await this.prisma.$transaction(async (tx) => {
+      const created = await tx.workspace.create({ data: { name, createdBy: userIdBig, updatedBy: userIdBig } });
+      await provisionDefaultRoles(tx, created.id);
+      const roles = await tx.role.findMany({ where: { workspaceId: created.id, slug: { in: WORKSPACE_CREATOR_ROLES } }, select: { id: true } });
+      await tx.workspaceMember.create({
+        data: { workspaceId: created.id, userId: userIdBig, roles: { create: roles.map((role) => ({ roleId: role.id })) } },
+      });
+      return created;
+    });
+    return {
+      id: workspace.id.toString(),
+      name: workspace.name,
+      createdAt: workspace.createdAt.toISOString(),
+      roles: [...WORKSPACE_CREATOR_ROLES].sort(),
+    };
+  }
+
+  async listForUser(userId: string): Promise<WorkspaceSummary[]> {
+    const memberships = await this.prisma.workspaceMember.findMany({
+      where: { userId: toId(userId), workspace: { isDeleted: false, isActive: true } },
+      include: { workspace: true, roles: { select: { role: { select: { slug: true } } } } },
+      orderBy: { createdAt: "asc" },
+    });
+    return memberships.map((m) => ({
+      id: m.workspace.id.toString(),
+      name: m.workspace.name,
+      createdAt: m.workspace.createdAt.toISOString(),
+      roles: m.roles.map((r) => r.role.slug).sort(),
+    }));
+  }
+
+  async listMembers(workspaceId: string): Promise<MembershipSummary[]> {
+    const rows = await this.prisma.workspaceMember.findMany({
+      where: { workspaceId: toId(workspaceId), user: { isDeleted: false } },
+      include: { user: true, roles: { select: { role: { select: { slug: true } } } } },
+      orderBy: { createdAt: "asc" },
+    });
+    return rows.map((row) => ({
+      memberId: row.id.toString(),
+      userId: row.userId.toString(),
+      email: row.user.email,
+      roles: row.roles.map((r) => r.role.slug).sort(),
+      createdAt: row.createdAt.toISOString(),
+    }));
+  }
+
+  private async resolveMemberRoles(workspaceIdBig: bigint, roleSlugs?: string[]) {
+    const roles = await this.prisma.role.findMany({
+      where: roleSlugs
+        ? { workspaceId: workspaceIdBig, slug: { in: roleSlugs }, isDeleted: false }
+        : { workspaceId: workspaceIdBig, isDefault: true, isActive: true, isDeleted: false },
+      select: { id: true, slug: true },
+    });
+    const unknown = (roleSlugs ?? []).filter((slug) => !roles.some((role) => role.slug === slug));
+    if (unknown.length) throw new NotFoundException(`role(s) not defined in this workspace: ${unknown.join(", ")}`);
+    return roles;
+  }
+
+  // Adds an existing user by email — there is no invite/email flow in this library. With no
+  // roles named, the new membership gets whichever of this workspace's roles are flagged `isDefault`.
+  async addMember(workspaceId: string, email: string, roleSlugs?: string[]): Promise<MembershipSummary> {
+    const workspaceIdBig = toId(workspaceId);
+    const user = await this.prisma.user.findUnique({ where: { email, isDeleted: false } });
+    if (!user) throw new NotFoundException("no user with that email");
+
+    const existing = await this.prisma.workspaceMember.findUnique({ where: { userId_workspaceId: { userId: user.id, workspaceId: workspaceIdBig } } });
+    if (existing) throw new ConflictException("already a member of this workspace");
+
+    const roles = await this.resolveMemberRoles(workspaceIdBig, roleSlugs);
+    const member = await this.prisma.workspaceMember.create({
+      data: { workspaceId: workspaceIdBig, userId: user.id, roles: { create: roles.map((role) => ({ roleId: role.id })) } },
+    });
+    return {
+      memberId: member.id.toString(),
+      userId: user.id.toString(),
+      email: user.email,
+      roles: roles.map((role) => role.slug).sort(),
+      createdAt: member.createdAt.toISOString(),
+    };
+  }
+
+  /**
+   * An administrator provisioning a brand-new account and adding it to this workspace in one
+   * step — as distinct from `addMember`, which only ever attaches an account that already
+   * exists. No invite/email flow in this library either way: the password is usable immediately.
+   */
+  async createMember(
+    workspaceId: string,
+    input: {
+      email: string;
+      passwordHash: string;
+      firstName?: string;
+      lastName?: string;
+      displayName?: string;
+      phone?: string;
+      username?: string;
+      photo?: string;
+      roles?: string[];
+    },
+    actorUserId: string | null,
+  ): Promise<MembershipSummary> {
+    const workspaceIdBig = toId(workspaceId);
+    const existing = await this.prisma.user.findUnique({ where: { email: input.email } });
+    if (existing) throw new ConflictException("email already registered");
+
+    const roles = await this.resolveMemberRoles(workspaceIdBig, input.roles);
+    const user = await this.prisma.user.create({
+      data: {
+        email: input.email,
+        passwordHash: input.passwordHash,
+        firstName: input.firstName,
+        lastName: input.lastName,
+        displayName: input.displayName,
+        phone: input.phone,
+        username: input.username,
+        photo: input.photo,
+        createdBy: actorUserId ? toId(actorUserId) : null,
+      },
+    });
+    const member = await this.prisma.workspaceMember.create({
+      data: { workspaceId: workspaceIdBig, userId: user.id, roles: { create: roles.map((role) => ({ roleId: role.id })) } },
+    });
+    return {
+      memberId: member.id.toString(),
+      userId: user.id.toString(),
+      email: user.email,
+      roles: roles.map((role) => role.slug).sort(),
+      createdAt: member.createdAt.toISOString(),
+    };
+  }
+
+  async removeMember(workspaceId: string, memberId: string): Promise<void> {
+    const workspaceIdBig = toId(workspaceId);
+    const memberIdBig = toId(memberId);
+    const member = await this.prisma.workspaceMember.findUnique({ where: { id: memberIdBig } });
+    if (!member || member.workspaceId !== workspaceIdBig) throw new NotFoundException("member not found in this workspace");
+
+    // Role assignments and direct grants belong to the membership, so `onDelete: Cascade` on
+    // both join tables takes them with it.
+    await this.prisma.workspaceMember.delete({ where: { id: memberIdBig } });
+    await this.rbac.invalidateMember(member.userId.toString(), workspaceId);
+  }
+}

package/registry/combos/nestjs-prisma/variants/workspaces/test/variant-hooks.ts

@@ -0,0 +1,333 @@
+// Variant hooks for the workspace variant. See test/harness.ts for the contract. Admin
+// authority here is per workspace — making someone an admin means giving them a workspace to be
+// admin of. `proveVariantProperties` carries the core security property: a role held in one
+// workspace grants nothing in another.
+import "dotenv/config";
+import { PrismaPg } from "@prisma/adapter-pg";
+import { PrismaClient } from "../generated/prisma/client.js";
+import { POLICY_VERSION_KEY } from "../src/permission-cache.js";
+import { permissionCacheStore } from "./bootstrap.js";
+import { renewingToken, type AdminSession, type Principal, type ProofContext, type VariantHooks } from "./harness.js";
+
+const prisma = new PrismaClient({ adapter: new PrismaPg({ connectionString: process.env["DATABASE_URL"] }) });
+
+interface Workspace {
+  id: string;
+  name: string;
+  roles: string[];
+}
+
+/** Signs up a fresh user, creates a workspace they administer, and returns both. */
+async function newAdminWithWorkspace(ctx: ProofContext, label: string) {
+  const email = ctx.uniqueEmail(label);
+  const password = `${label}-pw-12345`;
+  const tokens = await ctx.signup(email, password);
+  const userId = (await ctx.call("GET", "/auth/me", { token: tokens.accessToken })).body.sub as string;
+  const created = await ctx.call("POST", "/workspaces", { token: tokens.accessToken, body: { name: `${label}-workspace` } });
+  return { email, password, userId, token: tokens.accessToken, workspace: created.body as Workspace };
+}
+
+export const hooks: VariantHooks = {
+  variant: "workspaces",
+
+  async makeAdmin(ctx: ProofContext, principal: Principal): Promise<AdminSession> {
+    const created = await ctx.call("POST", "/workspaces", { token: principal.tokens.accessToken, body: { name: "proof-workspace" } });
+    ctx.assert(created.status === 201 || created.status === 200, `creating a workspace succeeds (got ${created.status})`);
+    const workspace = created.body as Workspace;
+    ctx.assert(workspace.roles.includes("admin"), "the creator of a workspace is an admin member of it");
+    // No re-login needed: the access token is workspace-agnostic and carries no authorization,
+    // so the membership is in effect immediately. freshToken() re-logs in anyway because the
+    // 2-second access-token TTL in test/bootstrap.ts can expire a token mid-section.
+    return {
+      token: principal.tokens.accessToken,
+      workspaceId: workspace.id,
+      freshToken: renewingToken(async () => {
+        const res = await ctx.call("POST", "/auth/login", { body: { identifier: principal.email, password: principal.password } });
+        return (res.body as { accessToken: string }).accessToken;
+      }),
+    };
+  },
+
+  async admitUser(ctx: ProofContext, admin: AdminSession, user: { userId: string; email: string }): Promise<void> {
+    const added = await ctx.call("POST", "/workspaces/members", { token: await admin.freshToken(), workspaceId: admin.workspaceId, body: { email: user.email } });
+    ctx.assert(added.status === 201 || added.status === 200, `adding a user to the workspace succeeds (got ${added.status})`);
+  },
+
+  async proveVariantProperties(ctx: ProofContext): Promise<void> {
+    // Two independent workspaces, each with its own admin.
+    const alpha = await newAdminWithWorkspace(ctx, "alpha");
+    const beta = await newAdminWithWorkspace(ctx, "beta");
+
+    ctx.assert(alpha.workspace.id !== beta.workspace.id, "two workspaces are distinct");
+
+    // --- a non-member cannot even see a workspace exists ---
+    const outsider = await ctx.call("GET", "/auth/admin/users", { token: alpha.token, workspaceId: beta.workspace.id });
+    ctx.assert(outsider.status === 403, `an admin of one workspace is refused in a workspace they are not a member of (got ${outsider.status})`);
+
+    const bogus = await ctx.call("GET", "/auth/admin/users", { token: alpha.token, workspaceId: "00000000-0000-0000-0000-000000000000" });
+    ctx.assert(bogus.status === 403, `an unknown workspace id is refused the same way as someone else's (got ${bogus.status})`);
+
+    const noHeader = await ctx.call("GET", "/auth/admin/users", { token: alpha.token });
+    ctx.assert(noHeader.status === 403, `a workspace-scoped route refuses a request that names no workspace (got ${noHeader.status})`);
+
+    // --- alpha joins beta as a plain member: their admin role in alpha must not follow them ---
+    const added = await ctx.call("POST", "/workspaces/members", { token: beta.token, workspaceId: beta.workspace.id, body: { email: alpha.email } });
+    ctx.assert(added.status === 201 || added.status === 200, `an admin can add an existing user to their workspace (got ${added.status})`);
+    const alphaInBeta = added.body as { memberId: string; roles: string[] };
+    ctx.assert(alphaInBeta.roles.join() === "member", `a new member defaults to the member role (got ${alphaInBeta.roles.join()})`);
+
+    const meInAlpha = await ctx.call("GET", "/auth/me", { token: alpha.token, workspaceId: alpha.workspace.id });
+    ctx.assert(meInAlpha.body.roles.includes("admin"), "the same token is admin in its own workspace");
+
+    const meInBeta = await ctx.call("GET", "/auth/me", { token: alpha.token, workspaceId: beta.workspace.id });
+    ctx.assert(!meInBeta.body.roles.includes("admin"), "THE core property: the admin role held in workspace A is absent in workspace B");
+    ctx.assert(meInBeta.body.roles.includes("member"), "…and only the roles granted by workspace B's membership apply there");
+
+    const adminAttemptInBeta = await ctx.call("GET", "/auth/admin/users", { token: alpha.token, workspaceId: beta.workspace.id });
+    ctx.assert(adminAttemptInBeta.status === 403, `being an admin elsewhere does not unlock workspace B's admin endpoints (got ${adminAttemptInBeta.status})`);
+
+    // --- roles are per workspace: the same role name can mean different things ---
+    const roleInBeta = await ctx.call("POST", "/auth/admin/roles", { token: beta.token, workspaceId: beta.workspace.id, body: { slug: "shared-name" } });
+    const roleInAlpha = await ctx.call("POST", "/auth/admin/roles", { token: alpha.token, workspaceId: alpha.workspace.id, body: { slug: "shared-name" } });
+    ctx.assert(roleInBeta.status === 201 && roleInAlpha.status === 201, "the same role name can exist independently in two workspaces");
+
+    await ctx.call("POST", `/auth/admin/roles/${(roleInBeta.body as { id: string }).id}/permissions`, {
+      token: beta.token,
+      workspaceId: beta.workspace.id,
+      body: { permission: "beta:only" },
+    });
+    await ctx.call("POST", `/auth/admin/users/${alpha.userId}/roles`, { token: beta.token, workspaceId: beta.workspace.id, body: { role: "shared-name" } });
+
+    const permsInBeta = await ctx.call("GET", "/auth/me", { token: alpha.token, workspaceId: beta.workspace.id });
+    ctx.assert(permsInBeta.body.permissions.includes("beta:only"), "a role assigned in workspace B grants its permissions in workspace B");
+    const permsInAlpha = await ctx.call("GET", "/auth/me", { token: alpha.token, workspaceId: alpha.workspace.id });
+    ctx.assert(!permsInAlpha.body.permissions.includes("beta:only"), "…and the identically-named role in workspace A does not carry them");
+
+    // --- direct grants attach to the membership, not the user ---
+    const directGrant = await ctx.call("POST", `/auth/admin/users/${alpha.userId}/permissions`, {
+      token: beta.token,
+      workspaceId: beta.workspace.id,
+      body: { permission: "beta:direct" },
+    });
+    ctx.assert(directGrant.status === 201 || directGrant.status === 200, `a direct grant inside workspace B succeeds (got ${directGrant.status})`);
+    const afterGrantBeta = await ctx.call("GET", "/auth/me", { token: alpha.token, workspaceId: beta.workspace.id });
+    ctx.assert(afterGrantBeta.body.permissions.includes("beta:direct"), "the direct grant applies in workspace B");
+    const afterGrantAlpha = await ctx.call("GET", "/auth/me", { token: alpha.token, workspaceId: alpha.workspace.id });
+    ctx.assert(!afterGrantAlpha.body.permissions.includes("beta:direct"), "the direct grant does not leak into workspace A");
+
+    // --- an admin cannot act on a user who is not in their workspace ---
+    const crossBlock = await ctx.call("POST", `/auth/admin/users/${beta.userId}/block`, { token: alpha.token, workspaceId: alpha.workspace.id });
+    ctx.assert(crossBlock.status === 404, `an admin cannot block a user who is not a member of their workspace (got ${crossBlock.status})`);
+
+    // --- audit log is scoped too ---
+    const betaAudit = await ctx.call("GET", "/auth/admin/audit-log", { token: beta.token, workspaceId: beta.workspace.id });
+    ctx.assert(betaAudit.status === 200, `an admin can read their workspace's audit log (got ${betaAudit.status})`);
+    ctx.assert(
+      (betaAudit.body.items as Array<{ workspaceId: string | null }>).every((e) => e.workspaceId === beta.workspace.id),
+      "the audit log never returns another workspace's entries",
+    );
+
+    // --- membership management ---
+    const myWorkspaces = await ctx.call("GET", "/workspaces", { token: alpha.token });
+    ctx.assert(myWorkspaces.status === 200, `a user can list the workspaces they belong to (got ${myWorkspaces.status})`);
+    const ids = (myWorkspaces.body as Workspace[]).map((w) => w.id);
+    ctx.assert(ids.includes(alpha.workspace.id) && ids.includes(beta.workspace.id), "the list covers every workspace the user is a member of");
+
+    const promote = await ctx.call("PUT", `/workspaces/members/${alphaInBeta.memberId}/roles`, {
+      token: beta.token,
+      workspaceId: beta.workspace.id,
+      body: { roles: ["member", "shared-name"] },
+    });
+    ctx.assert(promote.status === 200, `an admin can set a member's roles (got ${promote.status})`);
+
+    const memberList = await ctx.call("GET", "/workspaces/members", { token: alpha.token, workspaceId: beta.workspace.id });
+    ctx.assert(memberList.status === 200 && memberList.body.length === 2, `any member can list the workspace's members (got ${memberList.status})`);
+
+    const removed = await ctx.call("DELETE", `/workspaces/members/${alphaInBeta.memberId}`, { token: beta.token, workspaceId: beta.workspace.id });
+    ctx.assert(removed.status === 200, `an admin can remove a member (got ${removed.status})`);
+
+    const afterRemoval = await ctx.call("GET", "/auth/me", { token: alpha.token, workspaceId: beta.workspace.id });
+    ctx.assert(afterRemoval.status === 403, `a removed member loses access to the workspace immediately (got ${afterRemoval.status})`);
+
+    const stillInAlpha = await ctx.call("GET", "/auth/me", { token: alpha.token, workspaceId: alpha.workspace.id });
+    ctx.assert(stillInAlpha.status === 200 && stillInAlpha.body.roles.includes("admin"), "…while their own workspace is untouched — the same login still works");
+
+    // --- revocation is immediate here: the context is resolved per request, not per token ---
+    const immediate = await ctx.call("POST", `/auth/admin/users/${beta.userId}/permissions`, {
+      token: beta.token,
+      workspaceId: beta.workspace.id,
+      body: { permission: "probe:immediate" },
+    });
+    ctx.assert(immediate.status === 201 || immediate.status === 200, `a direct grant to oneself succeeds (got ${immediate.status})`);
+    const seen = await ctx.call("GET", "/auth/me", { token: beta.token, workspaceId: beta.workspace.id });
+    ctx.assert(seen.body.permissions.includes("probe:immediate"), "the grant is visible on the very next request, with no re-login");
+    await ctx.call("POST", `/auth/admin/users/${beta.userId}/permissions/${encodeURIComponent("probe:immediate")}/revoke`, {
+      token: beta.token,
+      workspaceId: beta.workspace.id,
+    });
+    const gone = await ctx.call("GET", "/auth/me", { token: beta.token, workspaceId: beta.workspace.id });
+    ctx.assert(!gone.body.permissions.includes("probe:immediate"), "…and the revocation lands on the very next request too, on the same token");
+
+    await proveNewWorkspaceIsProvisioned(ctx);
+    await proveWorkspaceHeaderCannotBeSkipped(ctx, alpha);
+    await proveTheCacheIsScopedAndReal(ctx, alpha, beta);
+    await proveARawDatabaseEditChangesEnforcement(ctx, beta);
+  },
+};
+
+// The lockout test: without `WorkspaceRepository.create` provisioning default roles in the same
+// transaction, a brand-new workspace has no `Role` rows, and its creator's ["admin", "member"]
+// would be names with nothing behind them — locked out with no way back in. Walks the entire
+// administrative surface of a brand-new workspace as the person who just created it.
+async function proveNewWorkspaceIsProvisioned(ctx: ProofContext): Promise<void> {
+  const creator = await newAdminWithWorkspace(ctx, "fresh");
+  const ws = creator.workspace.id;
+  const as = { token: creator.token, workspaceId: ws };
+  ctx.assert(creator.workspace.roles.includes("admin"), "the creator of a brand-new workspace holds the admin role in it");
+
+  const guestEmail = ctx.uniqueEmail("fresh-guest");
+  const guestTokens = await ctx.signup(guestEmail, "fresh-guest-pw-1");
+  const guestId = (await ctx.call("GET", "/auth/me", { token: guestTokens.accessToken })).body.sub as string;
+
+  const ok = (res: { status: number }) => res.status === 200 || res.status === 201;
+
+  const added = await ctx.call("POST", "/workspaces/members", { ...as, body: { email: guestEmail } });
+  ctx.assert(ok(added), `members:manage — the creator can add a member (got ${added.status})`);
+  const memberId = (added.body as { memberId: string }).memberId;
+
+  ctx.assert(ok(await ctx.call("GET", "/auth/admin/users", as)), "users:read — the creator can list the members");
+  ctx.assert(ok(await ctx.call("GET", "/auth/admin/audit-log", as)), "audit-log:read — the creator can read the audit log");
+
+  const role = await ctx.call("POST", "/auth/admin/roles", { ...as, body: { slug: "fresh-role" } });
+  ctx.assert(ok(role), `roles:manage — the creator can define a role (got ${role.status})`);
+  const attach = await ctx.call("POST", `/auth/admin/roles/${(role.body as { id: string }).id}/permissions`, { ...as, body: { permission: "fresh:probe" } });
+  ctx.assert(ok(attach), `roles:manage — the creator can say what that role carries (got ${attach.status})`);
+
+  ctx.assert(ok(await ctx.call("POST", `/auth/admin/users/${guestId}/roles`, { ...as, body: { role: "fresh-role" } })), "roles:assign — assign a role");
+  ctx.assert(ok(await ctx.call("POST", `/auth/admin/users/${guestId}/roles/fresh-role/revoke`, as)), "roles:assign — revoke a role");
+
+  ctx.assert(
+    ok(await ctx.call("POST", `/auth/admin/users/${guestId}/permissions`, { ...as, body: { permission: "fresh:direct" } })),
+    "permissions:grant — grant directly",
+  );
+  ctx.assert(
+    ok(await ctx.call("POST", `/auth/admin/users/${guestId}/permissions/${encodeURIComponent("fresh:direct")}/revoke`, as)),
+    "permissions:grant — revoke a direct grant",
+  );
+
+  ctx.assert(ok(await ctx.call("POST", `/auth/admin/users/${guestId}/block`, as)), "users:block — block a member");
+  ctx.assert(ok(await ctx.call("POST", `/auth/admin/users/${guestId}/unblock`, as)), "users:block — unblock a member");
+
+  ctx.assert(ok(await ctx.call("PUT", `/workspaces/members/${memberId}/roles`, { ...as, body: { roles: ["member"] } })), "roles:assign — set a member's roles");
+  ctx.assert(ok(await ctx.call("DELETE", `/workspaces/members/${memberId}`, as)), "members:manage — remove a member");
+
+  // A second workspace's "admin" is a different row that happens to share a name.
+  const other = await newAdminWithWorkspace(ctx, "fresh-other");
+  const trespass = await ctx.call("GET", "/auth/admin/users", { token: creator.token, workspaceId: other.workspace.id });
+  ctx.assert(trespass.status === 403, `being provisioned as admin of one new workspace grants nothing in another (got ${trespass.status})`);
+}
+
+// `X-Workspace-Id` is the only thing that says which workspace a request acts in, so a missing
+// or junk header must never reach a handler with no workspace resolved — and must deny the same
+// way a workspace you aren't a member of does, so a caller can't tell the two apart.
+async function proveWorkspaceHeaderCannotBeSkipped(ctx: ProofContext, member: { token: string; workspace: Workspace }): Promise<void> {
+  const cases: Array<[string, Record<string, string>]> = [
+    ["absent", {}],
+    ["empty", { "x-workspace-id": "" }],
+    ["whitespace", { "x-workspace-id": "   " }],
+    ["not a uuid", { "x-workspace-id": "not-a-uuid" }],
+    ["a sql fragment", { "x-workspace-id": "' OR 1=1 --" }],
+    ["absurdly long", { "x-workspace-id": "x".repeat(4096) }],
+  ];
+
+  for (const [label, headers] of cases) {
+    const admin = await ctx.call("GET", "/auth/admin/users", { token: member.token, headers });
+    ctx.assert(admin.status === 403, `a permission-gated admin route denies a request whose workspace id is ${label} (got ${admin.status})`);
+
+    const members = await ctx.call("GET", "/workspaces/members", { token: member.token, headers });
+    ctx.assert(members.status === 403, `a member-gated workspace route denies a request whose workspace id is ${label} (got ${members.status})`);
+  }
+
+  // An id that exists but isn't yours and one that exists nowhere must answer identically, body
+  // included, or the 403 becomes a workspace oracle.
+  const stranger = await newAdminWithWorkspace(ctx, "stranger");
+  const notYours = await ctx.call("GET", "/auth/admin/users", { token: member.token, workspaceId: stranger.workspace.id });
+  const notReal = await ctx.call("GET", "/auth/admin/users", { token: member.token, workspaceId: "00000000-0000-0000-0000-000000000000" });
+  ctx.assert(
+    notYours.status === notReal.status && notYours.body?.message === notReal.body?.message,
+    `someone else's workspace and a nonexistent one answer identically (${notYours.status}/${notYours.body?.message} vs ${notReal.status}/${notReal.body?.message})`,
+  );
+
+  // /auth/me works either way, since clients call it before they know which workspaces exist —
+  // it must answer with an empty context, never one borrowed from a workspace the user belongs to.
+  const meNoHeader = await ctx.call("GET", "/auth/me", { token: member.token });
+  ctx.assert(meNoHeader.status === 200, `GET /auth/me answers without a workspace header (got ${meNoHeader.status})`);
+  ctx.assert(
+    Array.isArray(meNoHeader.body?.roles) && meNoHeader.body.roles.length === 0 && meNoHeader.body.permissions.length === 0,
+    `…with empty roles and permissions rather than some workspace's (got roles=${JSON.stringify(meNoHeader.body?.roles)})`,
+  );
+  ctx.assert(meNoHeader.body?.sub && meNoHeader.body?.sessionId, "…while still identifying the user, which is what makes it callable before any workspace is chosen");
+
+  const meEmptyHeader = await ctx.call("GET", "/auth/me", { token: member.token, headers: { "x-workspace-id": "" } });
+  ctx.assert(
+    meEmptyHeader.status === 200 && meEmptyHeader.body.roles.length === 0,
+    `an empty workspace header is treated as naming no workspace, not as naming one (got ${meEmptyHeader.status})`,
+  );
+
+  const meBogusHeader = await ctx.call("GET", "/auth/me", { token: member.token, workspaceId: "00000000-0000-0000-0000-000000000000" });
+  ctx.assert(meBogusHeader.status === 403, `but a workspace id that is named and not yours is refused outright, even here (got ${meBogusHeader.status})`);
+}
+
+// The permission cache is keyed on the membership, not the user, so invalidating one workspace
+// must not flush another. Reads the very store the app resolves through, so "the second request
+// didn't touch the database" is a measurement rather than a claim.
+async function proveTheCacheIsScopedAndReal(
+  ctx: ProofContext,
+  alpha: { token: string; workspace: Workspace },
+  beta: { token: string; userId: string; workspace: Workspace },
+): Promise<void> {
+  const N = 8;
+  await ctx.call("GET", "/auth/me", { token: alpha.token, workspaceId: alpha.workspace.id }); // warm
+  const before = { ...permissionCacheStore.stats };
+  for (let i = 0; i < N; i += 1) await ctx.call("GET", "/auth/me", { token: alpha.token, workspaceId: alpha.workspace.id });
+  const after = permissionCacheStore.stats;
+  ctx.assert(
+    after.misses === before.misses && after.hits === before.hits + N,
+    `${N} identical workspace-scoped requests resolve the membership 0 further times — all ${N} were cache hits (misses +${after.misses - before.misses}, hits +${after.hits - before.hits})`,
+  );
+
+  // A grant inside beta must invalidate beta's entry and leave alpha's alone — the cache
+  // subject is the (user, workspace) pair.
+  await ctx.call("POST", `/auth/admin/users/${beta.userId}/permissions`, { token: beta.token, workspaceId: beta.workspace.id, body: { permission: "probe:cache" } });
+  const beforeAlpha = { ...permissionCacheStore.stats };
+  const alphaAfter = await ctx.call("GET", "/auth/me", { token: alpha.token, workspaceId: alpha.workspace.id });
+  ctx.assert(
+    permissionCacheStore.stats.misses === beforeAlpha.misses && alphaAfter.status === 200,
+    "a grant made in workspace B does not invalidate the caller's cached membership of workspace A",
+  );
+  const betaAfter = await ctx.call("GET", "/auth/me", { token: beta.token, workspaceId: beta.workspace.id });
+  ctx.assert((betaAfter.body?.permissions ?? []).includes("probe:cache"), "…while workspace B sees the grant on its very next request");
+  await ctx.call("POST", `/auth/admin/users/${beta.userId}/permissions/${encodeURIComponent("probe:cache")}/revoke`, {
+    token: beta.token,
+    workspaceId: beta.workspace.id,
+  });
+  const betaRevoked = await ctx.call("GET", "/auth/me", { token: beta.token, workspaceId: beta.workspace.id });
+  ctx.assert(!(betaRevoked.body?.permissions ?? []).includes("probe:cache"), "…and loses it again on the request after the revoke");
+}
+
+// Writes the row directly rather than through the admin API, ruling out any in-memory side
+// channel — a `psql` session would look exactly like this, bump included (permission-cache.ts).
+async function proveARawDatabaseEditChangesEnforcement(ctx: ProofContext, beta: { token: string; workspace: Workspace }): Promise<void> {
+  const opened = await ctx.call("GET", "/auth/admin/audit-log", { token: beta.token, workspaceId: beta.workspace.id });
+  ctx.assert(opened.status === 200, `the workspace admin can read the audit log to begin with (got ${opened.status})`);
+
+  await prisma.permission.update({ where: { slug: "audit-log:read" }, data: { isActive: false } });
+  await permissionCacheStore.bump(POLICY_VERSION_KEY);
+  const denied = await ctx.call("GET", "/auth/admin/audit-log", { token: beta.token, workspaceId: beta.workspace.id });
+  ctx.assert(denied.status === 403, `a permission deactivated by a raw database write stops opening its route (got ${denied.status})`);
+
+  await prisma.permission.update({ where: { slug: "audit-log:read" }, data: { isActive: true } });
+  await permissionCacheStore.bump(POLICY_VERSION_KEY);
+  const restored = await ctx.call("GET", "/auth/admin/audit-log", { token: beta.token, workspaceId: beta.workspace.id });
+  ctx.assert(restored.status === 200, `…and reactivating it in the database opens the route again (got ${restored.status})`);
+}