@simple-auth-kit/cli 1.0.0

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

@@ -0,0 +1,123 @@
+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.",
+};
+
+/**
+ * Workspace membership. Every route below that acts *inside* a workspace names it with the
+ * `X-Workspace-Id` header rather than a path segment — the same rule the `/auth/admin/*` routes
+ * follow, so there is exactly one way a request says which workspace it means.
+ *
+ * Three routes here are deliberately tier 2 — `@Authenticated()`, any logged-in caller — and the
+ * permission catalog mints no slugs for them. That is a decision written on each route, not an
+ * omission: a route carrying no tier marker at all does not survive startup (route-tiers.ts).
+ *   • `POST /workspaces` and `GET /workspaces` are outside every workspace — any authenticated
+ *     user may create one or list their own. There is no workspace whose permissions could be
+ *     checked, and gating them on a permission granted *inside* some other workspace would mean
+ *     your first workspace could only be created by someone who already had one.
+ *   • `GET /workspaces/members` is gated on membership itself: `WorkspaceGuard` already proved
+ *     the caller belongs to the workspace, and seeing who else is in a room you are in is not
+ *     an administrative capability.
+ * 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" — the
+    // default lives in a row, not in this line.
+    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-drizzle/variants/workspaces/src/workspace.repository.ts

@@ -0,0 +1,255 @@
+import { ConflictException, Inject, Injectable, NotFoundException } from "@nestjs/common";
+import { and, asc, eq, inArray } from "drizzle-orm";
+import { DRIZZLE_DB, type Database } from "./db.js";
+import { provisionDefaultRoles, WORKSPACE_CREATOR_ROLES } from "./rbac.defaults.js";
+import { RbacRepository } from "./rbac.repository.js";
+import { roleMember, roles, users, workspaceMembers, workspaces } from "./schema.js";
+import { toId, toIdOrNull } 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(DRIZZLE_DB) private readonly db: Database,
+    @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.
+   *
+   * The role provisioning is not optional garnish. `roles` is unique per `[workspaceId, slug]`, so
+   * a new workspace genuinely has no role rows: without them the creator's membership would point
+   * at nothing, resolve to zero permissions, and lock them out of the workspace they had just made
+   * the instant any route enforced a permission. The seeder only provisions the workspace *it*
+   * creates, so this path has to provision its own — from the same definition, which is why both
+   * call `provisionDefaultRoles` rather than each keeping a copy of the table.
+   */
+  async create(userId: string, name: string): Promise<WorkspaceSummary> {
+    const userIdBig = toId(userId);
+    const workspace = await this.db.transaction(async (tx) => {
+      const [created] = await tx.insert(workspaces).values({ name, createdBy: userIdBig, updatedBy: userIdBig }).returning();
+      await provisionDefaultRoles(tx, created.id);
+
+      const creatorRoles = await tx
+        .select({ id: roles.id })
+        .from(roles)
+        .where(and(eq(roles.workspaceId, created.id), inArray(roles.slug, WORKSPACE_CREATOR_ROLES)));
+      const [member] = await tx.insert(workspaceMembers).values({ workspaceId: created.id, userId: userIdBig }).returning({ id: workspaceMembers.id });
+      if (creatorRoles.length) {
+        await tx.insert(roleMember).values(creatorRoles.map((role) => ({ memberId: member.id, 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.db
+      .select({
+        memberId: workspaceMembers.id,
+        memberCreatedAt: workspaceMembers.createdAt,
+        id: workspaces.id,
+        name: workspaces.name,
+        createdAt: workspaces.createdAt,
+      })
+      .from(workspaceMembers)
+      .innerJoin(workspaces, and(eq(workspaces.id, workspaceMembers.workspaceId), eq(workspaces.isDeleted, false)))
+      .where(eq(workspaceMembers.userId, toId(userId)))
+      .orderBy(asc(workspaceMembers.createdAt));
+
+    const rolesByMember = await this.rolesByMember(memberships.map((m) => m.memberId));
+    return memberships.map((m) => ({
+      id: m.id.toString(),
+      name: m.name,
+      createdAt: m.createdAt.toISOString(),
+      roles: (rolesByMember.get(m.memberId.toString()) ?? []).sort(),
+    }));
+  }
+
+  async listMembers(workspaceId: string): Promise<MembershipSummary[]> {
+    const rows = await this.db
+      .select({
+        memberId: workspaceMembers.id,
+        userId: workspaceMembers.userId,
+        createdAt: workspaceMembers.createdAt,
+        email: users.email,
+      })
+      .from(workspaceMembers)
+      .innerJoin(users, and(eq(users.id, workspaceMembers.userId), eq(users.isDeleted, false)))
+      .where(eq(workspaceMembers.workspaceId, toId(workspaceId)))
+      .orderBy(asc(workspaceMembers.createdAt));
+
+    const rolesByMember = await this.rolesByMember(rows.map((r) => r.memberId));
+    return rows.map((row) => ({
+      memberId: row.memberId.toString(),
+      userId: row.userId.toString(),
+      email: row.email,
+      roles: (rolesByMember.get(row.memberId.toString()) ?? []).sort(),
+      createdAt: row.createdAt.toISOString(),
+    }));
+  }
+
+  /**
+   * Resolves the roles a new membership should hold, shared by `addMember` and `createMember`.
+   * With no roles named, whichever of this workspace's roles are flagged `isDefault` — not a slug
+   * spelled in code. Named slugs are validated against this workspace: naming one that doesn't
+   * exist here is rejected rather than silently granting nothing.
+   */
+  private async resolveMemberRoles(workspaceIdBig: bigint, roleSlugs?: string[]): Promise<{ id: bigint; slug: string }[]> {
+    const granted = await this.db
+      .select({ id: roles.id, slug: roles.slug })
+      .from(roles)
+      .where(
+        roleSlugs
+          ? and(eq(roles.workspaceId, workspaceIdBig), inArray(roles.slug, roleSlugs))
+          : and(eq(roles.workspaceId, workspaceIdBig), eq(roles.isDefault, true), eq(roles.isActive, true)),
+      );
+    const unknown = (roleSlugs ?? []).filter((slug) => !granted.some((role) => role.slug === slug));
+    if (unknown.length) throw new NotFoundException(`role(s) not defined in this workspace: ${unknown.join(", ")}`);
+    return granted;
+  }
+
+  /**
+   * Adds an existing user by email — there is no invite/email flow in this library, that is the
+   * consuming app's job. With no roles named, the new membership gets whichever of this
+   * workspace's roles are flagged `isDefault`, not a slug spelled in code.
+   */
+  async addMember(workspaceId: string, email: string, roleSlugs?: string[]): Promise<MembershipSummary> {
+    const workspaceIdBig = toId(workspaceId);
+    const [user] = await this.db.select({ id: users.id, email: users.email }).from(users).where(eq(users.email, email)).limit(1);
+    if (!user) throw new NotFoundException("no user with that email");
+
+    const [existing] = await this.db
+      .select({ id: workspaceMembers.id })
+      .from(workspaceMembers)
+      .where(and(eq(workspaceMembers.userId, user.id), eq(workspaceMembers.workspaceId, workspaceIdBig)))
+      .limit(1);
+    if (existing) throw new ConflictException("already a member of this workspace");
+
+    const granted = await this.resolveMemberRoles(workspaceIdBig, roleSlugs);
+
+    const member = await this.db.transaction(async (tx) => {
+      const [created] = await tx.insert(workspaceMembers).values({ workspaceId: workspaceIdBig, userId: user.id }).returning();
+      if (granted.length) await tx.insert(roleMember).values(granted.map((role) => ({ memberId: created.id, roleId: role.id })));
+      return created;
+    });
+
+    return {
+      memberId: member.id.toString(),
+      userId: user.id.toString(),
+      email: user.email,
+      roles: granted.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;
+      roles?: string[];
+    },
+    actorUserId: string | null,
+  ): Promise<MembershipSummary> {
+    const workspaceIdBig = toId(workspaceId);
+    const [existing] = await this.db.select({ id: users.id }).from(users).where(eq(users.email, input.email)).limit(1);
+    if (existing) throw new ConflictException("email already registered");
+
+    const granted = await this.resolveMemberRoles(workspaceIdBig, input.roles);
+    const [user] = await this.db
+      .insert(users)
+      .values({
+        email: input.email,
+        passwordHash: input.passwordHash,
+        firstName: input.firstName,
+        lastName: input.lastName,
+        displayName: input.displayName,
+        phone: input.phone,
+        username: input.username,
+        createdBy: toIdOrNull(actorUserId),
+      })
+      .returning();
+
+    const member = await this.db.transaction(async (tx) => {
+      const [created] = await tx.insert(workspaceMembers).values({ workspaceId: workspaceIdBig, userId: user.id }).returning();
+      if (granted.length) await tx.insert(roleMember).values(granted.map((role) => ({ memberId: created.id, roleId: role.id })));
+      return created;
+    });
+
+    return {
+      memberId: member.id.toString(),
+      userId: user.id.toString(),
+      email: user.email,
+      roles: granted.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.db
+      .select({ id: workspaceMembers.id, userId: workspaceMembers.userId, workspaceId: workspaceMembers.workspaceId })
+      .from(workspaceMembers)
+      .where(eq(workspaceMembers.id, memberIdBig))
+      .limit(1);
+    if (!member || member.workspaceId !== workspaceIdBig) throw new NotFoundException("member not found in this workspace");
+
+    // Role assignments and direct grants belong to the membership, so they go with it — that is
+    // the point of hanging them off the member row. `onDelete: "cascade"` on both join tables is
+    // what makes that a database guarantee rather than two deletes someone has to remember.
+    await this.db.delete(workspaceMembers).where(eq(workspaceMembers.id, memberIdBig));
+    // A removed member must lose access on their very next request, so their entry has to become
+    // unreachable — the resolution that replaces it returns "not a member", which is never cached.
+    await this.rbac.invalidateMember(member.userId.toString(), workspaceId);
+  }
+
+  /** One read for a page's role assignments rather than one per membership. */
+  private async rolesByMember(memberIds: bigint[]): Promise<Map<string, string[]>> {
+    if (!memberIds.length) return new Map();
+    const rows = await this.db
+      .select({ memberId: roleMember.memberId, slug: roles.slug })
+      .from(roleMember)
+      .innerJoin(roles, eq(roles.id, roleMember.roleId))
+      .where(inArray(roleMember.memberId, memberIds));
+
+    const byMember = new Map<string, string[]>();
+    for (const row of rows) {
+      const key = row.memberId.toString();
+      byMember.set(key, [...(byMember.get(key) ?? []), row.slug]);
+    }
+    return byMember;
+  }
+}