@podosoft/podokit 1.1.5 → 1.2.0

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

@@ -5,7 +5,11 @@ import {
 } from "@podosoft/podokit-contracts";
 import { OBJECT_STORAGE } from "@podosoft/podokit-runtime";
 import { Elysia, t } from "elysia";
+import { adminSessionRoutes } from "./admin-sessions/admin-sessions.routes";
+import { createSessionRevoker, type RevokeUserSessionApi } from "./admin-sessions/admin-sessions.revoker";
+import { AdminSessionsService } from "./admin-sessions/admin-sessions.service";
 import { AUTH } from "./auth/auth.module";
+import { getAuth } from "./auth/auth-provider";
 import {
   ACCESS_POLICY,
   DATABASE,
@@ -16,6 +20,7 @@ import {
 } from "./core/services";
 import { ProfileImageService } from "./profile-image/profile-image.service";
 import { PROFILE_IMAGE_POLICY } from "@podosoft/podokit-contracts";
+import { siteAssetRoutes } from "./site-assets/site-assets.routes";
 import {
   PUBLIC_SITE_KEYS,
   SiteSettingsService,
@@ -24,6 +29,7 @@ import { validateSiteSetting } from "./site-settings/site-settings.validation";
 
 export const SITE_SETTINGS = Symbol("site-settings") as ServiceKey<SiteSettingsService>;
 export const PROFILE_IMAGES = Symbol("profile-images") as ServiceKey<ProfileImageService>;
+export const ADMIN_SESSIONS = Symbol("admin-sessions") as ServiceKey<AdminSessionsService>;
 
 const ICON_TYPES = new Set([
   "image/svg+xml",
@@ -37,25 +43,25 @@ function currentImage(user: Record<string, unknown>): string | null {
   return typeof user.image === "string" ? user.image : null;
 }
 
-function responseBody(buffer: Buffer): ArrayBuffer {
-  return buffer.buffer.slice(
-    buffer.byteOffset,
-    buffer.byteOffset + buffer.byteLength,
-  ) as ArrayBuffer;
-}
-
 const adminPlugin: AppPlugin = ({ services }) => {
   const auth = services.resolve(AUTH);
   const site = services.resolve(SITE_SETTINGS);
   const profileImages = services.resolve(PROFILE_IMAGES);
 
   return new Elysia({ name: "podokit.admin" })
+    .use(adminSessionRoutes({
+      auth,
+      sessions: services.resolve(ADMIN_SESSIONS),
+      revoke: createSessionRevoker(() => getAuth().api as unknown as RevokeUserSessionApi),
+    }))
+    .use(siteAssetRoutes(site, profileImages))
     .get("/site/settings", async () => {
+      // The favicon fields are site.* rows too, so one read serves the response.
       const all = await site.getAll();
       const response: Record<string, string | boolean | null> = {};
       for (const key of PUBLIC_SITE_KEYS) response[key] = all[key] ?? null;
-      response.hasFavicon = (await site.get("faviconContentType")) !== null;
-      response.faviconVersion = await site.faviconVersion();
+      response.hasFavicon = all.faviconContentType !== undefined;
+      response.faviconVersion = all.faviconUpdatedAt ?? null;
       return response;
     }, {
       detail: { tags: ["site"], summary: "Get public site settings" },
@@ -87,15 +93,6 @@ const adminPlugin: AppPlugin = ({ services }) => {
       body: t.Object({ file: t.File() }),
       detail: { tags: ["site"], summary: "Upload the site favicon" },
     })
-    .get("/site/favicon", async () => {
-      const icon = await site.getFavicon();
-      if (!icon) throw new AppException("FAVICON_NOT_FOUND", "No favicon set", 404);
-      return new Response(responseBody(icon.body), {
-        headers: { "content-type": icon.contentType },
-      });
-    }, {
-      detail: { tags: ["site"], summary: "Get the site favicon" },
-    })
     .post("/account/profile-image", async ({ request, body, set }) => {
       const session = await auth.requireSession(request);
       const file = body.file;
@@ -122,22 +119,14 @@ const adminPlugin: AppPlugin = ({ services }) => {
       return profileImages.remove(currentImage(session.user), request.headers);
     }, {
       detail: { tags: ["account"], summary: "Remove the current user's profile image" },
-    })
-    .get("/profile-images/:fileName", async ({ params, set }) => {
-      const image = await profileImages.get(params.fileName);
-      set.headers["cache-control"] = "public, max-age=31536000, immutable";
-      return new Response(responseBody(image.body), {
-        headers: { "content-type": image.contentType },
-      });
-    }, {
-      params: t.Object({ fileName: t.String({ minLength: 1 }) }),
-      detail: { tags: ["account"], summary: "Get a public profile image" },
     });
 };
 
 export const adminModule: PodokitModule = {
   name: "admin-dashboard",
   configure: (_env, services): void => {
+    const database = services.resolve(DATABASE);
+    services.register(ADMIN_SESSIONS, new AdminSessionsService(database.sql, database.provider));
     const storage = services.resolve(OBJECT_STORAGE);
     const site = new SiteSettingsService(services.resolve(DATABASE).sql, storage);
     const profileImages = new ProfileImageService(storage, services.resolve(LOGGER));

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

@@ -7,11 +7,9 @@ import { ProfileImageService } from "./profile-image.service";
 describe("ProfileImageService account deletion cleanup", () => {
   const storage = {
     put: mock(async () => undefined),
-    get: mock(async () => ({
-      key: "profile-images/example.webp",
-      size: 0,
-      body: (async function* (): AsyncGenerator<Uint8Array> { yield Buffer.alloc(0); })(),
-    })),
+    get: mock(async () => null),
+    stat: mock(async () => null),
+    list: mock(async () => ({ keys: [] })),
     exists: mock(async () => true),
     getDownloadUrl: mock(async () => "https://example.com/image"),
     delete: mock(async () => undefined),

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

@@ -21,7 +21,7 @@ const CONTENT_TYPES: Record<string, string> = {
 };
 
 export interface StoredProfileImage {
-  body: Buffer;
+  object: ObjectData;
   contentType: string;
 }
 
@@ -33,12 +33,6 @@ export type UpdateAuthUser = (
 const updateAuthUser: UpdateAuthUser = (image, headers) =>
   getAuth().api.updateUser({ body: { image }, headers });
 
-async function objectBuffer(object: ObjectData): Promise<Buffer> {
-  const chunks: Uint8Array[] = [];
-  for await (const chunk of object.body) chunks.push(chunk);
-  return Buffer.concat(chunks);
-}
-
 export class ProfileImageService {
   private unregisterUserDeleted?: () => void;
 
@@ -86,18 +80,13 @@ export class ProfileImageService {
     return { image: null };
   }
 
+  /** The image with its content unread. */
   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 objectBuffer(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);
-    }
+    const object = key ? await this.storage.get(key) : null;
+    if (!object) throw new AppException(PROFILE_IMAGE_NOT_FOUND, "Profile image not found.", 404);
+    const extension = fileName.slice(fileName.lastIndexOf(".") + 1);
+    return { object, contentType: CONTENT_TYPES[extension] ?? "application/octet-stream" };
   }
 
   private keyFromFileName(fileName: string): string | null {

package/dist/templates/modules/admin-dashboard/files/apps/api/src/site-assets/site-assets.routes.spec.ts

@@ -0,0 +1,167 @@
+import { afterEach, describe, expect, mock, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { AppException } from "@podosoft/podokit-contracts";
+import { LocalObjectStore, type ObjectData } from "@podosoft/podokit-runtime";
+import { Elysia } from "elysia";
+import type { Logger } from "pino";
+import { ProfileImageService } from "../profile-image/profile-image.service";
+import type { SiteFavicon } from "../site-settings/site-settings.service";
+import { faviconCacheControl, IMMUTABLE_CACHE_CONTROL, siteAssetRoutes } from "./site-assets.routes";
+
+const PNG = Buffer.from(
+  "iVBORw0KGgoAAAANSUhEUgAAAAIAAAADAQMAAACDJEzCAAAAIGNIUk0AAHomAACAhAAA+gAAAIDoAAB1MAAA6mAAADqYAAAXcJy6UTwAAAAGUExURWYzmf///129H+IAAAABYktHRAH/Ai3eAAAAB3RJTUUH6gcVCSUTzXBDTwAAACV0RVh0ZGF0ZTpjcmVhdGUAMjAyNi0wNy0yMVQwOTozNzoxOSswMDowMOuehLIAAAAldEVYdGRhdGU6bW9kaWZ5ADIwMjYtMDctMjFUMDk6Mzc6MTkrMDA6MDCawzwOAAAAKHRFWHRkYXRlOnRpbWVzdGFtcAAyMDI2LTA3LTIxVDA5OjM3OjE5KzAwOjAwzdYd0QAAAAtJREFUCNdjYAABAAAGAAFm9MlsAAAAAElFTkSuQmCC",
+  "base64",
+);
+
+const directories: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(directories.splice(0).map((path) => rm(path, { recursive: true, force: true })));
+});
+
+async function localStore(): Promise<LocalObjectStore> {
+  const directory = await mkdtemp(join(tmpdir(), "podokit-site-assets-"));
+  directories.push(directory);
+  return new LocalObjectStore({ rootDirectory: directory });
+}
+
+interface TrackedObject {
+  object: ObjectData;
+  read: () => boolean;
+}
+
+function trackedObject(content: string): TrackedObject {
+  let read = false;
+  const bytes = Buffer.from(content);
+  return {
+    object: {
+      key: "site/favicon",
+      size: bytes.byteLength,
+      contentType: "application/octet-stream",
+      etag: "\"favicon-1\"",
+      lastModified: new Date("2026-01-02T03:04:05Z"),
+      body: new ReadableStream<Uint8Array>({
+        pull(controller): void {
+          read = true;
+          controller.enqueue(bytes);
+          controller.close();
+        },
+      }, { highWaterMark: 0 }),
+    },
+    read: () => read,
+  };
+}
+
+type Get = (path: string, headers?: Record<string, string>) => Promise<Response>;
+
+function app(
+  favicon: () => SiteFavicon | null,
+  profileImages: Pick<ProfileImageService, "get">,
+): Get {
+  const target = new Elysia()
+    .onError(({ error, set }) => {
+      if (!(error instanceof AppException)) return undefined;
+      set.status = error.statusCode;
+      return { code: error.code };
+    })
+    .use(siteAssetRoutes({ getFavicon: async () => favicon() }, profileImages));
+  return async (path, headers = {}) => target.handle(new Request(`http://localhost${path}`, { headers }));
+}
+
+const noProfileImages: Pick<ProfileImageService, "get"> = {
+  get: () => Promise.reject(new Error("unused")),
+};
+
+describe("GET /site/favicon", () => {
+  test("streams the favicon with the validated type and its validators", async () => {
+    const icon = trackedObject("<svg/>");
+    const get = app(() => ({ object: icon.object, contentType: "image/svg+xml", version: "1700" }), noProfileImages);
+    const response = await get("/site/favicon");
+
+    expect(response.status).toBe(200);
+    expect(response.headers.get("content-type")).toBe("image/svg+xml");
+    expect(response.headers.get("content-length")).toBe("6");
+    expect(response.headers.get("etag")).toBe("\"favicon-1\"");
+    expect(response.headers.get("last-modified")).toBe("Fri, 02 Jan 2026 03:04:05 GMT");
+    expect(await response.text()).toBe("<svg/>");
+  });
+
+  test("answers a current copy with 304 without reading storage", async () => {
+    const icon = trackedObject("<svg/>");
+    const get = app(() => ({ object: icon.object, contentType: "image/svg+xml", version: "1700" }), noProfileImages);
+    const response = await get("/site/favicon", { "if-none-match": "\"favicon-1\"" });
+
+    expect(response.status).toBe(304);
+    expect(await response.text()).toBe("");
+    expect(icon.read()).toBe(false);
+  });
+
+  test("caches the current version for good and revalidates any other URL", async () => {
+    const get = (path: string, headers: Record<string, string> = {}): Promise<Response> => {
+      const icon = trackedObject("<svg/>");
+      return app(() => ({ object: icon.object, contentType: "image/svg+xml", version: "1700" }), noProfileImages)(
+        path,
+        headers,
+      );
+    };
+
+    const current = await get("/site/favicon?v=1700");
+    expect(current.status).toBe(200);
+    expect(current.headers.get("cache-control")).toBe(IMMUTABLE_CACHE_CONTROL);
+
+    for (const path of ["/site/favicon?v=1600", "/site/favicon?v=", "/site/favicon"]) {
+      const response = await get(path);
+      expect(response.status, path).toBe(200);
+      expect(response.headers.get("cache-control"), path).toBe("no-cache");
+      expect(response.headers.get("etag"), path).toBe("\"favicon-1\"");
+    }
+
+    const revalidated = await get("/site/favicon?v=1600", { "if-none-match": "\"favicon-1\"" });
+    expect(revalidated.status).toBe(304);
+    expect(revalidated.headers.get("cache-control")).toBe("no-cache");
+    expect(faviconCacheControl(null, "")).toBe("no-cache");
+  });
+
+  test("returns 404 when no favicon is set", async () => {
+    const response = await app(() => null, noProfileImages)("/site/favicon");
+    expect(response.status).toBe(404);
+    expect(await response.json()).toEqual({ code: "FAVICON_NOT_FOUND" });
+  });
+});
+
+describe("GET /profile-images/:fileName", () => {
+  test("streams exactly the uploaded bytes as an immutable resource", async () => {
+    const store = await localStore();
+    const logger = { warn: mock(() => undefined) } as unknown as Logger;
+    const images = new ProfileImageService(store, logger, async () => undefined);
+    const { image } = await images.upload(null, { buffer: PNG, mimetype: "image/png", size: PNG.byteLength }, new Headers());
+    const path = image?.replace(/^\/api/, "") ?? "";
+    const get = app(() => null, images);
+
+    const response = await get(path);
+    expect(response.status).toBe(200);
+    expect(response.headers.get("content-type")).toBe("image/png");
+    expect(response.headers.get("cache-control")).toBe(IMMUTABLE_CACHE_CONTROL);
+    expect(response.headers.get("content-length")).toBe(String(PNG.byteLength));
+    expect(Buffer.from(await response.arrayBuffer()).equals(PNG)).toBe(true);
+
+    const revalidated = await get(path, { "if-none-match": response.headers.get("etag") ?? "" });
+    expect(revalidated.status).toBe(304);
+    expect(revalidated.headers.get("cache-control")).toBe(IMMUTABLE_CACHE_CONTROL);
+
+    await images.remove(image ?? null, new Headers());
+    expect((await get(path)).status).toBe(404);
+  });
+
+  test("returns 404 for names that are not managed images", async () => {
+    const store = await localStore();
+    const logger = { warn: mock(() => undefined) } as unknown as Logger;
+    const get = app(() => null, new ProfileImageService(store, logger, async () => undefined));
+
+    for (const name of ["missing.png", "123e4567-e89b-42d3-a456-426614174000.png", "..%2Fsite%2Ffavicon"]) {
+      expect((await get(`/profile-images/${name}`)).status).toBe(404);
+    }
+  });
+});

package/dist/templates/modules/admin-dashboard/files/apps/api/src/site-assets/site-assets.routes.ts

@@ -0,0 +1,50 @@
+import { AppException } from "@podosoft/podokit-contracts";
+import { objectResponse } from "@podosoft/podokit-runtime";
+import { Elysia, t } from "elysia";
+import type { ElysiaPlugin } from "../core/services";
+import type { ProfileImageService } from "../profile-image/profile-image.service";
+import type { SiteSettingsService } from "../site-settings/site-settings.service";
+
+export const IMMUTABLE_CACHE_CONTROL = "public, max-age=31536000, immutable";
+
+/**
+ * Pages link the favicon as `?v=<version>`, and a new upload changes the
+ * version, so that URL can be cached for good. Any other URL revalidates.
+ */
+export function faviconCacheControl(current: string | null, requested: string | undefined): string {
+  return current !== null && requested === current ? IMMUTABLE_CACHE_CONTROL : "no-cache";
+}
+
+/** Public images streamed from object storage with validators for 304 replies. */
+export function siteAssetRoutes(
+  site: Pick<SiteSettingsService, "getFavicon">,
+  profileImages: Pick<ProfileImageService, "get">,
+): ElysiaPlugin {
+  return new Elysia({ name: "podokit.admin.site-assets" })
+    .get("/site/favicon", async ({ request, query }) => {
+      const icon = await site.getFavicon();
+      if (!icon) throw new AppException("FAVICON_NOT_FOUND", "No favicon set", 404);
+      return objectResponse(request, icon.object, {
+        contentType: icon.contentType,
+        cacheControl: faviconCacheControl(icon.version, query.v),
+      });
+    }, {
+      query: t.Object({ v: t.Optional(t.String()) }),
+      detail: {
+        tags: ["site"],
+        summary: "Get the site favicon",
+        description: "Cached permanently when `v` is the current `faviconVersion`; revalidated otherwise.",
+      },
+    })
+    .get("/profile-images/:fileName", async ({ request, params }) => {
+      const image = await profileImages.get(params.fileName);
+      // Every upload gets a new random file name, so a name never changes content.
+      return objectResponse(request, image.object, {
+        contentType: image.contentType,
+        cacheControl: IMMUTABLE_CACHE_CONTROL,
+      });
+    }, {
+      params: t.Object({ fileName: t.String({ minLength: 1 }) }),
+      detail: { tags: ["account"], summary: "Get a public profile image" },
+    });
+}

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

@@ -0,0 +1,158 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { SQL } from "bun";
+import type { ObjectData, ObjectStore } from "@podosoft/podokit-runtime";
+import { SiteSettingsService } from "./site-settings.service";
+
+const favicon: ObjectData = {
+  key: "site/favicon",
+  size: 1,
+  etag: "\"icon\"",
+  lastModified: new Date(0),
+  body: new ReadableStream<Uint8Array>(),
+};
+const storage = {
+  put: async (): Promise<void> => undefined,
+  get: async (key: string): Promise<ObjectData | null> => (key === "site/favicon" ? favicon : null),
+} as unknown as ObjectStore;
+
+interface Harness {
+  service: SiteSettingsService;
+  reads: () => number;
+  holdNextRead: () => () => void;
+  advance: (milliseconds: number) => void;
+  failNextWrite: () => void;
+}
+
+describe("SiteSettingsService", () => {
+  let db: SQL;
+  let harness: Harness;
+
+  beforeEach(async () => {
+    db = new SQL(":memory:");
+    await db`CREATE TABLE "app_setting" ("key" TEXT PRIMARY KEY, "value" TEXT NOT NULL, "updatedAt" TEXT)`;
+    await db`INSERT INTO "app_setting" ("key", "value") VALUES ('site.name', 'Before'), ('require2fa', 'false')`;
+
+    let reads = 0;
+    let clock = 1_000;
+    let hold: Promise<void> | null = null;
+    let failWrite = false;
+    // Counts reads and can hold a read's result to interleave it with a write.
+    const counted = async (strings: TemplateStringsArray, ...values: unknown[]): Promise<unknown> => {
+      reads += 1;
+      const gate = hold;
+      hold = null;
+      const rows: unknown = await db(strings, ...values);
+      if (gate) await gate;
+      return rows;
+    };
+    const sql = Object.assign(counted, {
+      begin: <T>(work: (tx: SQL) => Promise<T>): Promise<T> =>
+        db.begin(async (tx) => {
+          const result = await work(tx as unknown as SQL);
+          if (failWrite) {
+            failWrite = false;
+            throw new Error("write failed");
+          }
+          return result;
+        }),
+    });
+    harness = {
+      service: new SiteSettingsService(sql as unknown as SQL, storage, () => clock),
+      reads: () => reads,
+      holdNextRead: () => {
+        let release: () => void = () => undefined;
+        hold = new Promise((resolve) => { release = resolve; });
+        return release;
+      },
+      advance: (milliseconds) => { clock += milliseconds; },
+      failNextWrite: () => { failWrite = true; },
+    };
+  });
+
+  afterEach(async () => {
+    await db.close();
+  });
+
+  test("serves concurrent and repeated reads from one query", async () => {
+    const results = await Promise.all([
+      harness.service.getAll(),
+      harness.service.getAll(),
+      harness.service.get("name"),
+      harness.service.faviconVersion(),
+    ]);
+    await harness.service.getAll();
+
+    expect(harness.reads()).toBe(1);
+    expect(results[0]).toEqual({ name: "Before" });
+    expect(results[2]).toBe("Before");
+    expect(results[3]).toBeNull();
+  });
+
+  test("reads again after the snapshot expires", async () => {
+    await harness.service.getAll();
+    harness.advance(2_999);
+    await harness.service.getAll();
+    expect(harness.reads()).toBe(1);
+
+    harness.advance(1);
+    await harness.service.getAll();
+    expect(harness.reads()).toBe(2);
+  });
+
+  test("returns a write to the next read immediately", async () => {
+    await harness.service.getAll();
+
+    const saved = await harness.service.setMany({ name: "After", locale: "ko" });
+
+    expect(saved).toEqual({ name: "After", locale: "ko" });
+    expect(await harness.service.getAll()).toEqual({ name: "After", locale: "ko" });
+  });
+
+  test("writes every key in one transaction", async () => {
+    harness.failNextWrite();
+
+    await expect(harness.service.setMany({ name: "After", locale: "ko" })).rejects.toThrow("write failed");
+
+    expect(await harness.service.getAll()).toEqual({ name: "Before" });
+  });
+
+  test("does not keep a read that raced a write", async () => {
+    const release = harness.holdNextRead();
+    const stale = harness.service.getAll();
+
+    await harness.service.setMany({ name: "After" });
+    release();
+
+    expect(await stale).toEqual({ name: "Before" });
+    expect(await harness.service.getAll()).toEqual({ name: "After" });
+  });
+
+  test("derives the favicon fields from the same snapshot", async () => {
+    await harness.service.setFavicon(new Uint8Array([1]), "image/png");
+    const reads = harness.reads();
+
+    const all = await harness.service.getAll();
+
+    expect(all.faviconContentType).toBe("image/png");
+    expect(await harness.service.faviconVersion()).toBe(all.faviconUpdatedAt ?? "missing");
+    expect(harness.reads()).toBe(reads);
+  });
+
+  test("returns the favicon unread with its type and version from the snapshot", async () => {
+    expect(await harness.service.getFavicon()).toBeNull();
+    await harness.service.setFavicon(new Uint8Array([1]), "image/png");
+    const reads = harness.reads();
+    const version = await harness.service.faviconVersion();
+
+    expect(await harness.service.getFavicon()).toEqual({ object: favicon, contentType: "image/png", version });
+    expect(version).toMatch(/^\d+$/);
+    expect(harness.reads()).toBe(reads);
+  });
+
+  test("copies the snapshot for each caller", async () => {
+    const first = await harness.service.getAll();
+    first.name = "Changed";
+
+    expect(await harness.service.getAll()).toEqual({ name: "Before" });
+  });
+});