@podosoft/podokit 0.13.0 → 0.15.0

package/dist/templates/modules/admin-dashboard/files/apps/api/src/profile-image/profile-image-upload.interceptor.ts

@@ -0,0 +1,39 @@
+import {
+  type CallHandler,
+  type ExecutionContext,
+  Injectable,
+  PayloadTooLargeException,
+} from "@nestjs/common";
+import { FileInterceptor } from "@nestjs/platform-express";
+import {
+  AppException,
+  PROFILE_IMAGE_POLICY,
+  PROFILE_IMAGE_TOO_LARGE,
+} from "@podosoft/podokit-contracts";
+import type { Observable } from "rxjs";
+
+const ProfileImageFileInterceptor = FileInterceptor("file", {
+  limits: { fileSize: PROFILE_IMAGE_POLICY.maxBytes },
+});
+
+/** Preserve a stable error code when Multer rejects an oversized request. */
+@Injectable()
+export class ProfileImageUploadInterceptor extends ProfileImageFileInterceptor {
+  override async intercept(
+    context: ExecutionContext,
+    next: CallHandler,
+  ): Promise<Observable<unknown>> {
+    try {
+      return await super.intercept(context, next);
+    } catch (error: unknown) {
+      if (error instanceof PayloadTooLargeException) {
+        throw new AppException(
+          PROFILE_IMAGE_TOO_LARGE,
+          "Profile image must be 2 MB or smaller.",
+          413,
+        );
+      }
+      throw error;
+    }
+  }
+}

package/dist/templates/modules/admin-dashboard/files/apps/api/src/profile-image/profile-image.controller.ts

@@ -0,0 +1,73 @@
+/// <reference types="multer" />
+import {
+  Controller,
+  Delete,
+  Get,
+  Param,
+  Post,
+  Req,
+  Res,
+  StreamableFile,
+  UploadedFile,
+  UseInterceptors,
+} from "@nestjs/common";
+import { ApiConsumes, ApiTags } from "@nestjs/swagger";
+import { Public, Session, type UserSession } from "@thallesp/nestjs-better-auth";
+import {
+  AppException,
+  PROFILE_IMAGE_REQUIRED,
+  type ProfileImageResponse,
+} from "@podosoft/podokit-contracts";
+import { fromNodeHeaders } from "better-auth/node";
+import type { Request, Response } from "express";
+import { ProfileImageService } from "./profile-image.service";
+import { ProfileImageUploadInterceptor } from "./profile-image-upload.interceptor";
+
+@ApiTags("account")
+@Controller()
+export class ProfileImageController {
+  constructor(private readonly profileImages: ProfileImageService) {}
+
+  @Post("account/profile-image")
+  @ApiConsumes("multipart/form-data")
+  @UseInterceptors(ProfileImageUploadInterceptor)
+  async upload(
+    @Session() session: UserSession,
+    @Req() req: Request,
+    @UploadedFile() file?: Express.Multer.File,
+  ): Promise<ProfileImageResponse> {
+    if (!file) {
+      throw new AppException(
+        PROFILE_IMAGE_REQUIRED,
+        "A profile image file is required.",
+      );
+    }
+    return this.profileImages.upload(
+      session.user.image ?? null,
+      file,
+      fromNodeHeaders(req.headers),
+    );
+  }
+
+  @Delete("account/profile-image")
+  async remove(
+    @Session() session: UserSession,
+    @Req() req: Request,
+  ): Promise<ProfileImageResponse> {
+    return this.profileImages.remove(
+      session.user.image ?? null,
+      fromNodeHeaders(req.headers),
+    );
+  }
+
+  @Public()
+  @Get("profile-images/:fileName")
+  async get(
+    @Param("fileName") fileName: string,
+    @Res({ passthrough: true }) response: Response,
+  ): Promise<StreamableFile> {
+    const image = await this.profileImages.get(fileName);
+    response.setHeader("Cache-Control", "public, max-age=31536000, immutable");
+    return new StreamableFile(image.body, { type: image.contentType });
+  }
+}

package/dist/templates/modules/admin-dashboard/files/apps/api/src/profile-image/profile-image.module.ts

@@ -0,0 +1,9 @@
+import { Module } from "@nestjs/common";
+import { ProfileImageController } from "./profile-image.controller";
+import { ProfileImageService } from "./profile-image.service";
+
+@Module({
+  controllers: [ProfileImageController],
+  providers: [ProfileImageService],
+})
+export class ProfileImageModule {}

package/dist/templates/modules/admin-dashboard/files/apps/api/src/profile-image/profile-image.service.spec.ts

@@ -0,0 +1,43 @@
+import { afterAll, afterEach, describe, expect, it, jest } from "@jest/globals";
+import { runUserDeletedHandlers } from "../auth/user-delete-handlers";
+import { StorageService } from "../storage/storage.service";
+import { ProfileImageService } from "./profile-image.service";
+
+jest.mock("../auth/auth-provider", () => ({ getAuth: jest.fn() }));
+
+describe("ProfileImageService account deletion cleanup", () => {
+  const storage = {
+    put: jest.fn(async () => undefined),
+    get: jest.fn(async () => Buffer.alloc(0)),
+    presignedGetUrl: jest.fn(async () => "https://example.com/image"),
+    delete: jest.fn(async () => undefined),
+  };
+  const service = new ProfileImageService(storage as unknown as StorageService);
+
+  service.onModuleInit();
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  afterAll(() => {
+    service.onModuleDestroy();
+  });
+
+  it("deletes a managed image after the account is deleted", async () => {
+    await runUserDeletedHandlers({
+      id: "user-1",
+      image: "/api/profile-images/123e4567-e89b-42d3-a456-426614174000.webp",
+    });
+
+    expect(storage.delete).toHaveBeenCalledWith(
+      "profile-images/123e4567-e89b-42d3-a456-426614174000.webp",
+    );
+  });
+
+  it("does not delete an external identity-provider image", async () => {
+    await runUserDeletedHandlers({ id: "user-1", image: "https://example.com/avatar.png" });
+
+    expect(storage.delete).not.toHaveBeenCalled();
+  });
+});

package/dist/templates/modules/admin-dashboard/files/apps/api/src/profile-image/profile-image.service.ts

@@ -0,0 +1,110 @@
+import { randomUUID } from "node:crypto";
+import { Injectable, Logger, type OnModuleDestroy, type OnModuleInit } from "@nestjs/common";
+import {
+  AppException,
+  PROFILE_IMAGE_NOT_FOUND,
+  type ProfileImageResponse,
+} from "@podosoft/podokit-contracts";
+import { getAuth } from "../auth/auth-provider";
+import { registerUserDeletedHandler } from "../auth/user-delete-handlers";
+import { StorageService } from "../storage/storage.service";
+import { validateProfileImage, type ProfileImageUpload } from "./profile-image.validation";
+
+const FILE_NAME = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\.(?:jpg|png|webp)$/;
+const PUBLIC_PREFIX = "/api/profile-images/";
+const STORAGE_PREFIX = "profile-images/";
+
+const CONTENT_TYPES: Record<string, string> = {
+  jpg: "image/jpeg",
+  png: "image/png",
+  webp: "image/webp",
+};
+
+export interface StoredProfileImage {
+  body: Buffer;
+  contentType: string;
+}
+
+@Injectable()
+export class ProfileImageService implements OnModuleInit, OnModuleDestroy {
+  private readonly logger = new Logger(ProfileImageService.name);
+  private unregisterUserDeleted?: () => void;
+
+  constructor(private readonly storage: StorageService) {}
+
+  onModuleInit(): void {
+    this.unregisterUserDeleted = registerUserDeletedHandler(async (user) => {
+      await this.deleteManagedImage(user.image ?? null);
+    });
+  }
+
+  onModuleDestroy(): void {
+    this.unregisterUserDeleted?.();
+  }
+
+  async upload(
+    currentImage: string | null,
+    file: ProfileImageUpload,
+    headers: Headers,
+  ): Promise<ProfileImageResponse> {
+    const metadata = validateProfileImage(file);
+    const fileName = `${randomUUID()}.${metadata.extension}`;
+    const key = STORAGE_PREFIX + fileName;
+    const image = PUBLIC_PREFIX + fileName;
+
+    await this.storage.put(key, file.buffer, metadata.contentType);
+    try {
+      await getAuth().api.updateUser({ body: { image }, headers });
+    } catch (error: unknown) {
+      await this.deleteKeyBestEffort(key);
+      throw error;
+    }
+    await this.deleteManagedImage(currentImage);
+    return { image };
+  }
+
+  async remove(currentImage: string | null, headers: Headers): Promise<ProfileImageResponse> {
+    await getAuth().api.updateUser({ body: { image: null }, headers });
+    await this.deleteManagedImage(currentImage);
+    return { image: null };
+  }
+
+  async get(fileName: string): Promise<StoredProfileImage> {
+    const key = this.keyFromFileName(fileName);
+    if (!key) {
+      throw new AppException(PROFILE_IMAGE_NOT_FOUND, "Profile image not found.", 404);
+    }
+    try {
+      const extension = fileName.slice(fileName.lastIndexOf(".") + 1);
+      return { body: await this.storage.get(key), contentType: CONTENT_TYPES[extension] ?? "application/octet-stream" };
+    } catch {
+      throw new AppException(PROFILE_IMAGE_NOT_FOUND, "Profile image not found.", 404);
+    }
+  }
+
+  private keyFromFileName(fileName: string): string | null {
+    return FILE_NAME.test(fileName) ? STORAGE_PREFIX + fileName : null;
+  }
+
+  private keyFromPublicUrl(image: string | null): string | null {
+    if (!image?.startsWith(PUBLIC_PREFIX)) return null;
+    return this.keyFromFileName(image.slice(PUBLIC_PREFIX.length));
+  }
+
+  private async deleteManagedImage(image: string | null): Promise<void> {
+    const key = this.keyFromPublicUrl(image);
+    if (key) await this.deleteKeyBestEffort(key);
+  }
+
+  private async deleteKeyBestEffort(key: string): Promise<void> {
+    try {
+      await this.storage.delete(key);
+    } catch (error: unknown) {
+      this.logger.warn({
+        message: "Delete profile image object failed",
+        key,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+}

package/dist/templates/modules/admin-dashboard/files/apps/api/src/profile-image/profile-image.validation.spec.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from "@jest/globals";
+import {
+  AppException,
+  PROFILE_IMAGE_DIMENSIONS_INVALID,
+  PROFILE_IMAGE_POLICY,
+  PROFILE_IMAGE_TOO_LARGE,
+  PROFILE_IMAGE_TYPE_INVALID,
+} from "@podosoft/podokit-contracts";
+import { validateProfileImage, type ProfileImageUpload } from "./profile-image.validation";
+
+const PNG = "iVBORw0KGgoAAAANSUhEUgAAAAIAAAADAQMAAACDJEzCAAAAIGNIUk0AAHomAACAhAAA+gAAAIDoAAB1MAAA6mAAADqYAAAXcJy6UTwAAAAGUExURWYzmf///129H+IAAAABYktHRAH/Ai3eAAAAB3RJTUUH6gcVCSUTzXBDTwAAACV0RVh0ZGF0ZTpjcmVhdGUAMjAyNi0wNy0yMVQwOTozNzoxOSswMDowMOuehLIAAAAldEVYdGRhdGU6bW9kaWZ5ADIwMjYtMDctMjFUMDk6Mzc6MTkrMDA6MDCawzwOAAAAKHRFWHRkYXRlOnRpbWVzdGFtcAAyMDI2LTA3LTIxVDA5OjM3OjE5KzAwOjAwzdYd0QAAAAtJREFUCNdjYAABAAAGAAFm9MlsAAAAAElFTkSuQmCC";
+const JPEG = "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAMCAgICAgMCAgIDAwMDBAYEBAQEBAgGBgUGCQgKCgkICQkKDA8MCgsOCwkJDRENDg8QEBEQCgwSExIQEw8QEBD/2wBDAQMDAwQDBAgEBAgQCwkLEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBD/wAARCAAKAAoDAREAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAj/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFgEBAQEAAAAAAAAAAAAAAAAAAAYH/8QAFBEBAAAAAAAAAAAAAAAAAAAAAP/aAAwDAQACEQMRAD8AnpuCtAAAf//Z";
+const WEBP = "UklGRjQAAABXRUJQVlA4ICgAAACQAQCdASoCAAMAAgA0JaACdLoAA5gA/vCwN/8bx4FeS7K/1oWg+AAA";
+const TOO_WIDE_PNG = "iVBORw0KGgoAAAANSUhEUgAACAEAAAABAQMAAACfGLePAAAAIGNIUk0AAHomAACAhAAA+gAAAIDoAAB1MAAA6mAAADqYAAAXcJy6UTwAAAAGUExURWYzmf///129H+IAAAABYktHRAH/Ai3eAAAAB3RJTUUH6gcVCScoTk3I6QAAACV0RVh0ZGF0ZTpjcmVhdGUAMjAyNi0wNy0yMVQwOTozOTo0MCswMDowMCgv/7YAAAAldEVYdGRhdGU6bW9kaWZ5ADIwMjYtMDctMjFUMDk6Mzk6NDArMDA6MDBZckcKAAAAKHRFWHRkYXRlOnRpbWVzdGFtcAAyMDI2LTA3LTIxVDA5OjM5OjQwKzAwOjAwDmdm1QAAAAxJREFUGNNjYBjpAAABAgABRf+HpwAAAABJRU5ErkJggg==";
+
+function upload(base64: string, mimetype: string, size?: number): ProfileImageUpload {
+  const buffer = Buffer.from(base64, "base64");
+  return { buffer, mimetype, size: size ?? buffer.length };
+}
+
+function expectAppException(action: () => void, code: string, statusCode = 400): void {
+  try {
+    action();
+    throw new Error("Expected validation to throw");
+  } catch (error: unknown) {
+    expect(error).toBeInstanceOf(AppException);
+    expect(error).toMatchObject({ code, statusCode });
+  }
+}
+
+describe("validateProfileImage", () => {
+  const supported: Array<[string, string, "png" | "jpg" | "webp", number, number]> = [
+    [PNG, "image/png", "png", 2, 3],
+    [JPEG, "image/jpeg", "jpg", 10, 10],
+    [WEBP, "image/webp", "webp", 2, 3],
+  ];
+
+  it.each(supported)("accepts a valid supported image", (base64, mimetype, extension, width, height) => {
+    expect(validateProfileImage(upload(base64, mimetype))).toMatchObject({
+      contentType: mimetype,
+      extension,
+      width,
+      height,
+    });
+  });
+
+  it("rejects a MIME type that does not match the bytes", () => {
+    expectAppException(
+      () => validateProfileImage(upload(PNG, "image/jpeg")),
+      PROFILE_IMAGE_TYPE_INVALID,
+    );
+  });
+
+  it("rejects unsupported or malformed bytes", () => {
+    expectAppException(
+      () => validateProfileImage(upload(Buffer.from("not an image").toString("base64"), "image/png")),
+      PROFILE_IMAGE_TYPE_INVALID,
+    );
+  });
+
+  it("rejects a file larger than the shared byte limit", () => {
+    expectAppException(
+      () => validateProfileImage(upload(PNG, "image/png", PROFILE_IMAGE_POLICY.maxBytes + 1)),
+      PROFILE_IMAGE_TOO_LARGE,
+      413,
+    );
+  });
+
+  it("accepts arbitrary aspect ratios within the limit", () => {
+    expect(validateProfileImage(upload(PNG, "image/png"))).toMatchObject({ width: 2, height: 3 });
+  });
+
+  it("rejects a dimension above 2048 pixels", () => {
+    expectAppException(
+      () => validateProfileImage(upload(TOO_WIDE_PNG, "image/png")),
+      PROFILE_IMAGE_DIMENSIONS_INVALID,
+    );
+  });
+});

package/dist/templates/modules/admin-dashboard/files/apps/api/src/profile-image/profile-image.validation.ts

@@ -0,0 +1,74 @@
+import {
+  AppException,
+  PROFILE_IMAGE_DIMENSIONS_INVALID,
+  PROFILE_IMAGE_POLICY,
+  PROFILE_IMAGE_TOO_LARGE,
+  PROFILE_IMAGE_TYPE_INVALID,
+  type ProfileImageMimeType,
+} from "@podosoft/podokit-contracts";
+import { imageSize } from "image-size";
+
+export interface ProfileImageUpload {
+  buffer: Buffer;
+  mimetype: string;
+  size: number;
+}
+
+export interface ProfileImageMetadata {
+  contentType: ProfileImageMimeType;
+  extension: "jpg" | "png" | "webp";
+  width: number;
+  height: number;
+}
+
+const DETECTED_TYPES: Record<string, Pick<ProfileImageMetadata, "contentType" | "extension">> = {
+  jpg: { contentType: "image/jpeg", extension: "jpg" },
+  png: { contentType: "image/png", extension: "png" },
+  webp: { contentType: "image/webp", extension: "webp" },
+};
+
+/** Inspect image bytes instead of trusting the uploaded filename or MIME type. */
+export function validateProfileImage(file: ProfileImageUpload): ProfileImageMetadata {
+  if (Math.max(file.size, file.buffer.length) > PROFILE_IMAGE_POLICY.maxBytes) {
+    throw new AppException(
+      PROFILE_IMAGE_TOO_LARGE,
+      "Profile image must be 2 MB or smaller.",
+      413,
+    );
+  }
+
+  let dimensions: ReturnType<typeof imageSize>;
+  try {
+    dimensions = imageSize(file.buffer);
+  } catch {
+    throw new AppException(
+      PROFILE_IMAGE_TYPE_INVALID,
+      "Profile image must be a valid PNG, JPEG, or WebP file.",
+    );
+  }
+
+  const detected = dimensions.type ? DETECTED_TYPES[dimensions.type] : undefined;
+  if (!detected || detected.contentType !== file.mimetype) {
+    throw new AppException(
+      PROFILE_IMAGE_TYPE_INVALID,
+      "Profile image must be a valid PNG, JPEG, or WebP file.",
+    );
+  }
+  if (
+    dimensions.width === undefined
+    || dimensions.height === undefined
+    || dimensions.width > PROFILE_IMAGE_POLICY.maxWidth
+    || dimensions.height > PROFILE_IMAGE_POLICY.maxHeight
+  ) {
+    throw new AppException(
+      PROFILE_IMAGE_DIMENSIONS_INVALID,
+      "Profile image dimensions must not exceed 2048 by 2048 pixels.",
+    );
+  }
+
+  return {
+    ...detected,
+    width: dimensions.width,
+    height: dimensions.height,
+  };
+}

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/admin/registry.svelte.ts

@@ -6,7 +6,7 @@ import type { Messages } from "$lib/i18n/messages";
 
 // Module-driven admin menu registry. Modules append their sidebar nav entries and
 // settings tabs at the markers below via `podo add` injection, so the admin menu
-// grows and shrinks with the installed module set — no edits to app-sidebar or
+// grows and shrinks with the installed module set — no edits to admin-sidebar or
 // the settings page. Empty until a module registers.
 
 /** A sidebar nav entry contributed by a module: a link, a label resolved from the

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/components/account-menu.svelte

@@ -7,12 +7,30 @@
   import LayoutDashboardIcon from "@lucide/svelte/icons/layout-dashboard";
   import LogOutIcon from "@lucide/svelte/icons/log-out";
   import UserIcon from "@lucide/svelte/icons/user";
+  import ChevronsUpDownIcon from "@lucide/svelte/icons/chevrons-up-down";
   import { api } from "$lib/api";
   import { getI18n } from "$lib/i18n";
+  import { cn } from "$lib/utils";
   import type { SessionUser } from "../../app.d.ts";
   import UserAvatar from "./user-avatar.svelte";
 
-  let { user }: { user: SessionUser | null } = $props();
+  type MenuSide = "top" | "right" | "bottom" | "left";
+  type MenuAlign = "start" | "center" | "end";
+  type Props = {
+    user: SessionUser | null;
+    variant?: "avatar" | "identity";
+    side?: MenuSide;
+    align?: MenuAlign;
+    class?: string;
+  };
+
+  let {
+    user,
+    variant = "avatar",
+    side = "bottom",
+    align = "end",
+    class: className,
+  }: Props = $props();
   const i18n = getI18n();
   const loginHref = $derived(withAuthRedirect("/login", currentPath(page.url)));
 
@@ -27,12 +45,25 @@
   <DropdownMenu.Root>
     <DropdownMenu.Trigger
       data-testid="account-menu"
-      class="hover:bg-muted focus-visible:border-ring focus-visible:ring-ring/50 inline-flex size-8 items-center justify-center rounded-full outline-none focus-visible:ring-3"
+      class={cn(
+        "hover:bg-muted focus-visible:border-ring focus-visible:ring-ring/50 outline-none focus-visible:ring-3",
+        variant === "avatar"
+          ? "inline-flex size-8 items-center justify-center rounded-full"
+          : "flex w-full items-center gap-2 rounded-md p-2 text-left",
+        className,
+      )}
       aria-label={i18n.t.nav.account}
     >
       <UserAvatar {user} class="size-8" />
+      {#if variant === "identity"}
+        <div class="min-w-0 flex-1 text-sm leading-tight">
+          <span class="block truncate font-medium">{user.name}</span>
+          <span class="text-muted-foreground block truncate text-xs">{user.email}</span>
+        </div>
+        <ChevronsUpDownIcon class="size-4 shrink-0" />
+      {/if}
     </DropdownMenu.Trigger>
-    <DropdownMenu.Content align="end" class="w-56">
+    <DropdownMenu.Content {align} {side} class="w-56">
       <DropdownMenu.Label>
         <span class="block truncate font-medium">{user.name}</span>
         <span class="text-muted-foreground block truncate text-xs font-normal">{user.email}</span>
@@ -47,5 +78,5 @@
     </DropdownMenu.Content>
   </DropdownMenu.Root>
 {:else}
-  <Button data-testid="sign-in-link" href={loginHref} variant="ghost">{i18n.t.auth.signIn}</Button>
+  <Button data-testid="sign-in-link" href={loginHref} variant="ghost" class={className}>{i18n.t.auth.signIn}</Button>
 {/if}