@podosoft/podokit 0.17.4 → 1.0.2

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/account/+page.svelte

@@ -1,23 +1,27 @@
 <script lang="ts">
-  import AccountPage from "$lib/components/account-page.svelte";
-  import LanguageSwitch from "$lib/components/language-switch.svelte";
-  import SiteFooter from "$lib/components/site-footer.svelte";
-  import ThemeToggle from "$lib/components/theme-toggle.svelte";
-  import { Button } from "$lib/components/ui/button";
-  import { Toaster } from "$lib/components/ui/sonner";
-  import { getI18n } from "$lib/i18n";
+  import AccountPage from "#lib/components/account-page.svelte";
+  import ImpersonationBanner from "#lib/components/impersonation-banner.svelte";
+  import LanguageSwitch from "#lib/components/language-switch.svelte";
+  import SiteFooter from "#lib/components/site-footer.svelte";
+  import ThemeToggle from "#lib/components/theme-toggle.svelte";
+  import { Button } from "#lib/components/ui/button/index.js";
+  import { Toaster } from "#lib/components/ui/sonner/index.js";
+  import { getI18n } from "#lib/i18n/index.js";
   import type { Capabilities } from "@podosoft/podokit-api-client";
   import type { SessionUser } from "../../app.d.ts";
 
   let {
     data,
   }: {
-    data: { user: SessionUser; currentSessionId: string | null; capabilities: Capabilities };
+    data: { user: SessionUser; currentSessionId: string | null; capabilities: Capabilities; impersonating: boolean };
   } = $props();
   const i18n = getI18n();
 </script>
 
 <div class="flex min-h-svh flex-col">
+  {#if data.impersonating}
+    <ImpersonationBanner email={data.user.email} />
+  {/if}
   <header class="flex h-14 items-center gap-2 border-b px-4">
     <Button href="/" variant="ghost">{i18n.t.nav.home}</Button>
     <div class="flex-1"></div>

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/maintenance/+page.svelte

@@ -1,10 +1,10 @@
 <script lang="ts">
   // Shown to non-admin visitors while maintenance mode is on (see +layout.server.ts).
   // Admins are never redirected here and can sign in to turn it off.
-  import { Button } from "$lib/components/ui/button";
-  import LanguageSwitch from "$lib/components/language-switch.svelte";
-  import ThemeToggle from "$lib/components/theme-toggle.svelte";
-  import { getI18n } from "$lib/i18n";
+  import { Button } from "#lib/components/ui/button/index.js";
+  import LanguageSwitch from "#lib/components/language-switch.svelte";
+  import ThemeToggle from "#lib/components/theme-toggle.svelte";
+  import { getI18n } from "#lib/i18n/index.js";
 
   const i18n = getI18n();
 </script>

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/oauth2/consent/+page.svelte

@@ -1,8 +1,8 @@
 <script lang="ts">
   import { page } from "$app/state";
-  import { Button } from "$lib/components/ui/button";
-  import * as Card from "$lib/components/ui/card";
-  import { getI18n } from "$lib/i18n";
+  import { Button } from "#lib/components/ui/button/index.js";
+  import * as Card from "#lib/components/ui/card/index.js";
+  import { getI18n } from "#lib/i18n/index.js";
 
   const i18n = getI18n();
   // The OAuth provider redirects here with the authorization request in the query

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/setup-2fa/+page.server.ts

@@ -1,6 +1,6 @@
 import { redirect } from "@sveltejs/kit";
 import type { PageServerLoad } from "./$types";
-import { requireBackendAvailable } from "$lib/server/guards";
+import { requireBackendAvailable } from "#lib/server/guards.js";
 
 // The mandatory two-factor enrolment page (reached via the require-2fa gate).
 // Must be signed in; already-enrolled users have nothing to do here.

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/setup-2fa/+page.svelte

@@ -1,14 +1,14 @@
 <script lang="ts">
   import { goto } from "$app/navigation";
   import QRCode from "qrcode";
-  import { Button } from "$lib/components/ui/button";
-  import { Input } from "$lib/components/ui/input";
-  import { Label } from "$lib/components/ui/label";
-  import { Checkbox } from "$lib/components/ui/checkbox";
-  import * as Card from "$lib/components/ui/card";
-  import * as Alert from "$lib/components/ui/alert";
-  import { api } from "$lib/api";
-  import { getI18n } from "$lib/i18n";
+  import { Button } from "#lib/components/ui/button/index.js";
+  import { Input } from "#lib/components/ui/input/index.js";
+  import { Label } from "#lib/components/ui/label/index.js";
+  import { Checkbox } from "#lib/components/ui/checkbox/index.js";
+  import * as Card from "#lib/components/ui/card/index.js";
+  import * as Alert from "#lib/components/ui/alert/index.js";
+  import { api } from "#lib/api.js";
+  import { getI18n } from "#lib/i18n/index.js";
 
   const i18n = getI18n();
   let password = $state("");
@@ -39,7 +39,11 @@
       error = e.code === "INVALID_PASSWORD" ? i18n.t.setup2fa.wrongPassword : i18n.t.setup2fa.enableFailed;
       return;
     }
-    setup = { totpURI: data?.totpURI ?? "", backupCodes: (data?.backupCodes ?? []) as string[] };
+    if (!data || !("totpURI" in data) || !data.totpURI || !Array.isArray(data.backupCodes)) {
+      error = i18n.t.setup2fa.enableFailed;
+      return;
+    }
+    setup = { totpURI: data.totpURI, backupCodes: data.backupCodes };
   }
 
   async function activate(): Promise<void> {

package/dist/templates/modules/admin-dashboard/files/dot-claude/skills/podokit-data-table/SKILL.md

@@ -5,15 +5,15 @@ description: Use when building ANY list or table view in this project (users, se
 
 # Build a list with the shared DataTable
 
-**Every** list/table in this project must use `$lib/components/data-table.svelte`
+**Every** list/table in this project must use `#lib/components/data-table.svelte`
 (`DataTable`) — it provides sortable headers and a footer pagination, consistently.
 Do **not** assemble `Table.Root` / `Table.Header` / `Table.Body` by hand, and don't
 put pagination outside the table.
 
 ```svelte
 <script lang="ts">
-  import DataTable from "$lib/components/data-table.svelte";
-  import { cn } from "$lib/utils";
+  import DataTable from "#lib/components/data-table.svelte";
+  import { cn } from "#lib/utils.js";
   const columns = [
     { key: "name", label: "Name", sortable: true },
     { key: "email", label: "Email", sortable: true },

package/dist/templates/modules/admin-dashboard/files/tests/helpers/accounts.ts

@@ -13,7 +13,7 @@ export type Account = { name: string; email: string; password: string };
  * So the constant is a DEFAULT and the environment wins:
  *
  * ```bash
- * E2E_BASE_URL=https://app.example.com E2E_ADMIN_PASSWORD='…' npx playwright test …
+ * E2E_BASE_URL=https://app.example.com E2E_ADMIN_PASSWORD='…' {{packageExecutor}} playwright test …
  * ```
  *
  * Without the override the run fails with `INVALID_EMAIL_OR_PASSWORD`, which is the correct
@@ -29,4 +29,19 @@ export const USER = { name: "Normal User", email: "user@example.com", password:
 export const adminState = "playwright/.auth/admin.json";
 export const userState = "playwright/.auth/user.json";
 export const userBaselineState = "playwright/.auth/user-baseline.json";
-export const anonState = { cookies: [], origins: [] } as const;
+const testUrl = new URL(process.env.E2E_BASE_URL ?? "http://localhost:5001");
+export const anonState = {
+  cookies: [
+    {
+      name: "locale",
+      value: "en",
+      domain: testUrl.hostname,
+      path: "/",
+      expires: -1,
+      httpOnly: false,
+      secure: testUrl.protocol === "https:",
+      sameSite: "Lax" as const,
+    },
+  ],
+  origins: [],
+};

package/dist/templates/modules/admin-dashboard/files/tests/helpers/disposable-users.ts

@@ -3,6 +3,7 @@ import {
   test as base,
   type APIResponse,
 } from "@playwright/test";
+import { ADMIN } from "./accounts";
 
 const baseURL = process.env.E2E_BASE_URL ?? "http://localhost:5001";
 const origin = { origin: baseURL };
@@ -29,11 +30,23 @@ async function readCreatedUserId(response: APIResponse): Promise<string> {
 }
 
 export const test = base.extend<{ disposableUsers: DisposableUsers }>({
-  disposableUsers: async ({ context }, use) => {
-    // Reuse the browser context's storageState-backed request client. Creating
-    // a second admin login here can revoke the browser session in applications
-    // that enforce a single concurrent session.
-    const request = context.request;
+  disposableUsers: async ({ context, playwright }, use, testInfo) => {
+    // API projects do not inherit the UI project's admin storageState, while a
+    // second admin sign-in can invalidate the shared UI session. Authenticate an
+    // isolated request context only for API tests and reuse browser cookies for UI.
+    let request = context.request;
+    let ownsRequest = false;
+    if (testInfo.project.name === "api") {
+      request = await playwright.request.newContext({
+        baseURL,
+        extraHTTPHeaders: origin,
+      });
+      ownsRequest = true;
+      const signIn = await request.post("/api/auth/sign-in/email", {
+        data: { email: ADMIN.email, password: ADMIN.password },
+      });
+      expect(signIn.ok(), "sign in disposable user fixture").toBeTruthy();
+    }
     const userIds = new Set<string>();
 
     const disposableUsers: DisposableUsers = {
@@ -67,14 +80,18 @@ export const test = base.extend<{ disposableUsers: DisposableUsers }>({
     try {
       await use(disposableUsers);
     } finally {
-      for (const userId of userIds) {
-        const response = await request.post("/api/auth/admin/remove-user", {
-          headers: origin,
-          data: { userId },
-        });
-        if (!response.ok() && response.status() !== 404) {
-          throw new Error(`Failed to remove disposable user ${userId}: HTTP ${response.status()}`);
+      try {
+        for (const userId of userIds) {
+          const response = await request.post("/api/auth/admin/remove-user", {
+            headers: origin,
+            data: { userId },
+          });
+          if (!response.ok() && response.status() !== 404) {
+            throw new Error(`Failed to remove disposable user ${userId}: HTTP ${response.status()}`);
+          }
         }
+      } finally {
+        if (ownsRequest) await request.dispose();
       }
     }
   },

package/dist/templates/modules/admin-dashboard/files/tests/helpers/hydration.ts

@@ -1,9 +1,9 @@
 import type { Page } from "@playwright/test";
 
-// SvelteKit dev hydration can attach event handlers slightly after load;
-// wait for the page to settle before driving client-only interactions.
+// Wait for SvelteKit to attach client event handlers before driving forms. The
+// root layout adds this marker from onMount, so no fixed timing assumption is
+// needed even while the development server compiles a route for the first time.
 export async function ready(page: Page, path: string): Promise<void> {
   await page.goto(path);
-  await page.waitForLoadState("load");
-  await page.waitForTimeout(400);
+  await page.locator('html[data-hydrated="true"]').waitFor();
 }

package/dist/templates/modules/admin-dashboard/files/tests/ui/account.ui.spec.ts

@@ -226,6 +226,57 @@ test("account nav shows the core sections", async ({ page }) => {
   await expect(page.getByRole("button", { name: "Sessions" })).toBeVisible();
 });
 
+test("connected account unlink uses the local account row id @smoke", async ({ page }) => {
+  const provider = "google";
+  let unlinkBody: unknown;
+  await page.route("**/api/auth/list-accounts", (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: "application/json",
+      body: JSON.stringify([
+        { id: "local-account-id", providerId: provider, accountId: "provider-subject" },
+      ]),
+    }),
+  );
+  await page.route("**/api/auth/unlink-account", async (route) => {
+    unlinkBody = route.request().postDataJSON();
+    await route.fulfill({ status: 200, contentType: "application/json", body: "{}" });
+  });
+
+  try {
+    const enabled = await page.request.put("/api/account/auth-config", {
+      data: {
+        social: {
+          [provider]: {
+            enabled: true,
+            clientId: "podokit",
+            clientSecret: "podokit",
+          },
+        },
+      },
+    });
+    expect(enabled.ok()).toBeTruthy();
+    await expect
+      .poll(async () => {
+        const response = await page.request.get("/api/account/capabilities");
+        const body = (await response.json()) as { providers?: string[] };
+        return body.providers ?? [];
+      }, { timeout: 8_000 })
+      .toContain(provider);
+
+    await ready(page, "/admin/account");
+    await page.getByRole("button", { name: "Connected", exact: true }).click();
+    await page.getByRole("button", { name: "Disconnect", exact: true }).click();
+
+    await expect.poll(() => unlinkBody).toEqual({ accountId: "local-account-id" });
+    await expect(page.getByText("Disconnected", { exact: true })).toBeVisible();
+  } finally {
+    await page.request.put("/api/account/auth-config", {
+      data: { social: { [provider]: { enabled: false } } },
+    });
+  }
+});
+
 test("two-factor setup shows a scannable QR code when enabled", async ({ page }) => {
   await ready(page, "/admin/account");
   await page.getByRole("button", { name: "Security" }).click();

package/dist/templates/modules/admin-dashboard/files/tests/ui/auth.ui.spec.ts

@@ -9,7 +9,7 @@ const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
 
 test("login page renders @smoke", async ({ page }) => {
   await page.goto("/login");
-  await expect(page.getByLabel("Email")).toBeVisible();
+  await expect(page.getByRole("textbox", { name: /Email(?: or username)?/ })).toBeVisible();
   await expect(page.getByLabel("Password")).toBeVisible();
   await expect(page.getByRole("button", { name: "Sign in", exact: true })).toBeVisible();
   await expect(page.getByRole("link", { name: "Sign up" })).toBeVisible();
@@ -18,7 +18,7 @@ test("login page renders @smoke", async ({ page }) => {
 
 test("invalid credentials show an error", async ({ page }) => {
   await ready(page, "/login");
-  await page.getByLabel("Email").fill("nobody@example.com");
+  await page.getByRole("textbox", { name: /Email(?: or username)?/ }).fill("nobody@example.com");
   await page.getByLabel("Password").fill("wrong-password");
   await page.getByRole("button", { name: "Sign in", exact: true }).click();
   await expect(page.getByRole("alert")).toBeVisible();

package/dist/templates/modules/admin-dashboard/files/tests/ui/impersonation.ui.spec.ts

@@ -13,11 +13,13 @@ test("admin can impersonate a user and stop", async ({ page }) => {
   await row.getByRole("button").click();
   await page.getByRole("menuitem", { name: "Impersonate" }).click();
 
-  // Impersonating drops us into the app with a banner offering to stop.
-  await expect(page).toHaveURL(/\/admin(\/|$)/);
+  // Impersonating a normal user leaves the admin-only route group and keeps a
+  // visible route back to the original administrator session.
+  await expect(page).toHaveURL(/\/account(\/|$)/);
   const stop = page.getByRole("button", { name: "Stop impersonating" });
   await expect(stop).toBeVisible();
 
   await stop.click();
+  await expect(page).toHaveURL(/\/admin(\/|$)/);
   await expect(page.getByRole("button", { name: "Stop impersonating" })).toHaveCount(0);
 });

package/dist/templates/modules/admin-dashboard/files/tests/ui/oidc.ui.spec.ts

@@ -3,7 +3,9 @@ import { createHash, randomBytes } from "node:crypto";
 
 // admin storageState (project default) — the admin is the resource owner.
 const b64url = (b: Buffer): string => b.toString("base64url");
-const REDIRECT = "http://localhost:9999/callback";
+// This front-channel test stops at consent, so use the HTTPS callback required
+// for a web client without depending on a live relying-party callback server.
+const REDIRECT = "https://example.com/callback";
 
 // Verifies the provider is correctly configured end to end on the front channel:
 // signed discovery + JWKS, dynamic client registration, and an authorize request
@@ -12,7 +14,11 @@ const REDIRECT = "http://localhost:9999/callback";
 // docs/modules.md for the manual round-trip checklist.
 test("OIDC provider: discovery, JWKS, client registration, authorize handoff", async ({ page, baseURL }) => {
   const headers = { origin: baseURL ?? "" };
-  await page.request.put("/api/account/settings", { data: { oidcProvider: true }, headers });
+  const enabled = await page.request.put("/api/account/settings", {
+    data: { oidcProvider: true },
+    headers,
+  });
+  expect(enabled.ok(), await enabled.text()).toBeTruthy();
   await expect
     .poll(async () => (await page.request.get("/api/auth/.well-known/openid-configuration")).status(), { timeout: 8000 })
     .toBe(200);
@@ -30,12 +36,13 @@ test("OIDC provider: discovery, JWKS, client registration, authorize handoff", a
     // the provider is enabled the auth instance may still be rebuilding.
     let reg: { client_id?: string; client_secret?: string } = {};
     await expect(async () => {
-      reg = await (
-        await page.request.post("/api/auth/oauth2/create-client", {
-          data: { client_name: "E2E RP", redirect_uris: [REDIRECT] },
-          headers,
-        })
-      ).json();
+      const response = await page.request.post("/api/auth/oauth2/create-client", {
+        data: { client_name: "E2E RP", redirect_uris: [REDIRECT] },
+        headers,
+      });
+      const body = await response.text();
+      expect(response.ok(), body).toBeTruthy();
+      reg = JSON.parse(body) as typeof reg;
       expect(reg.client_id).toBeTruthy();
     }).toPass({ timeout: 8000 });
     expect(reg.client_secret).toBeTruthy();
@@ -48,14 +55,20 @@ test("OIDC provider: discovery, JWKS, client registration, authorize handoff", a
       `/api/auth/oauth2/authorize?client_id=${reg.client_id}&redirect_uri=${encodeURIComponent(REDIRECT)}` +
       `&response_type=code&scope=${encodeURIComponent("openid profile email")}&state=st` +
       `&code_challenge=${challenge}&code_challenge_method=S256`;
-    const authz = await (await page.request.get(authorizeUrl, { headers })).json();
-    expect(String(authz.url)).toContain("/oauth2/consent");
-    expect(String(authz.url)).toContain("client_id=");
+    const authz = await page.request.get(authorizeUrl, { headers, maxRedirects: 0 });
+    expect(authz.status()).toBe(302);
+    const consentUrl = authz.headers().location ?? "";
+    expect(consentUrl).toContain("/oauth2/consent");
+    expect(consentUrl).toContain("client_id=");
 
     // The consent page renders (reached in a real browser navigation).
-    await page.goto(authz.url);
+    await page.goto(consentUrl);
     await expect(page.getByRole("button", { name: "Allow" })).toBeVisible();
   } finally {
-    await page.request.put("/api/account/settings", { data: { oidcProvider: false }, headers });
+    const disabled = await page.request.put("/api/account/settings", {
+      data: { oidcProvider: false },
+      headers,
+    });
+    expect(disabled.ok(), await disabled.text()).toBeTruthy();
   }
 });

package/dist/templates/modules/admin-dashboard/files/tests/ui/passkey.ui.spec.ts

@@ -1,8 +1,9 @@
 import { expect, test } from "@playwright/test";
+import { anonState } from "../helpers/accounts";
 import { ready } from "../helpers/hydration";
 
 // Full passkey round trip on a throwaway account — never touches the shared admin.
-test.use({ storageState: { cookies: [], origins: [] } });
+test.use({ storageState: anonState });
 
 test("register a passkey and sign in with it", async ({ page, baseURL }) => {
   const origin = { origin: baseURL ?? "" };
@@ -20,7 +21,7 @@ test("register a passkey and sign in with it", async ({ page, baseURL }) => {
   const signup = await page.context().request.post("/api/auth/sign-up/email", { data: { email, password: pw, name: "PK" }, headers: origin });
   expect(signup.ok(), await signup.text()).toBeTruthy();
 
-  await ready(page, "/admin/account");
+  await ready(page, "/account");
   await page.getByRole("button", { name: "Security" }).click();
   const addBtn = page.getByRole("button", { name: "Add passkey" });
   test.skip((await addBtn.count()) === 0, "passkeys not enabled");

package/dist/templates/modules/admin-dashboard/module.manifest.json

@@ -35,13 +35,13 @@
   "packageOverlays": {
     "api": {
       "dependencies": {
-        "image-size": "^2.0.2"
+        "probe-image-size": "^7.4.0"
       },
       "devDependencies": {
-        "@types/multer": "^1.4.12"
+        "@types/probe-image-size": "^7.2.5"
       },
       "scripts": {
-        "admin:bootstrap": "node scripts/bootstrap-admin.mjs"
+        "admin:bootstrap": "bun scripts/bootstrap-admin.mjs"
       }
     }
   },
@@ -75,8 +75,8 @@
         },
         {
           "path": "apps/web/src/routes/(admin)/+layout.svelte",
-          "from": "$lib/components/app-sidebar.svelte",
-          "to": "$lib/components/admin-sidebar.svelte",
+          "from": "#lib/components/app-sidebar.svelte",
+          "to": "#lib/components/admin-sidebar.svelte",
           "expected": 1
         }
       ]
@@ -87,7 +87,7 @@
       "file": "apps/web/src/routes/+page.svelte",
       "marker": "// podokit:end:landing-imports",
       "optional": true,
-      "text": "import { page } from \"$app/state\";\n  import AccountMenu from \"$lib/components/account-menu.svelte\";\n  import LanguageSwitch from \"$lib/components/language-switch.svelte\";\n  import ThemeToggle from \"$lib/components/theme-toggle.svelte\";"
+      "text": "import { page } from \"$app/state\";\n  import AccountMenu from \"#lib/components/account-menu.svelte\";\n  import LanguageSwitch from \"#lib/components/language-switch.svelte\";\n  import ThemeToggle from \"#lib/components/theme-toggle.svelte\";"
     },
     {
       "file": "apps/web/src/routes/+page.svelte",
@@ -119,32 +119,22 @@
       "file": "AGENTS.md",
       "marker": "<!-- podokit:end:agents-modules -->",
       "optional": true,
-      "text": "### admin-dashboard\n- The `(admin)` route group and `admin-sidebar.svelte` are the admin-console shell for `/admin/*` only. Put signed-in product pages in `(app)` or in a separate route group with its own layout; do not place them under `(admin)`.\n- Admin console lives at `/admin/*` (users, sessions, organizations, audit, settings, account). Set `ADMIN_EMAILS`, then create or verify the initial account with `npm run admin:bootstrap -w <app>-api`; never commit or persist `ADMIN_BOOTSTRAP_PASSWORD`. When sign-up approval is enabled, self-registered users stay pending until an administrator approves them on `/admin/users`; administrator-created users bypass the queue.\n- Signed-in users can upload, replace, or remove their profile image from `/account` or `/admin/account`. Keep the shared policy visible in custom account UI: PNG, JPEG, or WebP; at most 2 MB and 2048 by 2048 pixels. Use the managed `/api/account/profile-image` endpoints instead of writing directly to storage or `user.image`.\n- `sidebar-user-menu.svelte` is specific to the admin sidebar. For a product shell outside `Sidebar.Provider`, use the managed `<AccountMenu {user} variant=\"identity\" side=\"top\" />` component.\n- Custom protected server layouts must call `requireBackendAvailable(locals)` from `$lib/server/guards` before redirecting anonymous users. This preserves sessions and returns 503 when authentication or maintenance policy cannot be checked.\n- **Every list/table MUST use the shared `$lib/components/data-table.svelte` (`DataTable`)** \u2014 it gives sortable headers + a footer pagination. Add search/filters with `$lib/components/table-toolbar.svelte`. Never assemble `Table.Root`/`Table.Header`/`Table.Body` by hand. For responsive columns, use `hideBelow` and apply the row context's `cellClass(columnKey)` to the matching cell.\n"
+      "text": "### admin-dashboard\n- The `(admin)` route group and `admin-sidebar.svelte` are the admin-console shell for `/admin/*` only. Put signed-in product pages in `(app)` or in a separate route group with its own layout; do not place them under `(admin)`.\n- Admin console lives at `/admin/*` (users, sessions, organizations, audit, settings, account). Set `ADMIN_EMAILS`, then create or verify the initial account with `{{apiRun}} admin:bootstrap{{apiWorkspaceArg}}`; never commit or persist `ADMIN_BOOTSTRAP_PASSWORD`. When sign-up approval is enabled, self-registered users stay pending until an administrator approves them on `/admin/users`; administrator-created users bypass the queue.\n- Signed-in users can upload, replace, or remove their profile image from `/account` or `/admin/account`. Keep the shared policy visible in custom account UI: PNG, JPEG, or WebP; at most 2 MB and 2048 by 2048 pixels. Use the managed `/api/account/profile-image` endpoints instead of writing directly to storage or `user.image`.\n- `sidebar-user-menu.svelte` is specific to the admin sidebar. For a product shell outside `Sidebar.Provider`, use the managed `<AccountMenu {user} variant=\"identity\" side=\"top\" />` component.\n- Custom protected server layouts must call `requireBackendAvailable(locals)` from `#lib/server/guards.js` before redirecting anonymous users. This preserves sessions and returns 503 when authentication or maintenance policy cannot be checked.\n- **Every list/table MUST use the shared `#lib/components/data-table.svelte` (`DataTable`)** \u2014 it gives sortable headers + a footer pagination. Add search/filters with `#lib/components/table-toolbar.svelte`. Never assemble `Table.Root`/`Table.Header`/`Table.Body` by hand. For responsive columns, use `hideBelow` and apply the row context's `cellClass(columnKey)` to the matching cell.\n"
     },
     {
-      "file": "apps/api/src/app.module.ts",
+      "file": "apps/api/src/app.ts",
       "marker": "// podokit:end:imports",
-      "text": "import { SiteSettingsModule } from \"./site-settings/site-settings.module\";"
+      "text": "import { adminModule } from \"./admin.module\";"
     },
     {
-      "file": "apps/api/src/app.module.ts",
-      "marker": "// podokit:end:imports",
-      "text": "import { ProfileImageModule } from \"./profile-image/profile-image.module\";"
-    },
-    {
-      "file": "apps/api/src/app.module.ts",
-      "marker": "// podokit:end:module-imports",
-      "text": "SiteSettingsModule,"
-    },
-    {
-      "file": "apps/api/src/app.module.ts",
-      "marker": "// podokit:end:module-imports",
-      "text": "ProfileImageModule,"
+      "file": "apps/api/src/app.ts",
+      "marker": "// podokit:end:modules",
+      "text": "adminModule,"
     }
   ],
   "instructions": [
-    "Set ADMIN_EMAILS in .env (comma-separated). After building and migrating, inject ADMIN_BOOTSTRAP_EMAIL and ADMIN_BOOTSTRAP_PASSWORD for one command only, then run npm run admin:bootstrap -w <app>-api. The command creates a verified, approved admin or safely verifies an existing one.",
-    "Re-run the auth migration to add the admin and sign-up approval columns:  npx @better-auth/cli migrate -y --config apps/api/src/auth/auth.ts",
+    "Set ADMIN_EMAILS in .env (comma-separated). After building and migrating, inject ADMIN_BOOTSTRAP_EMAIL and ADMIN_BOOTSTRAP_PASSWORD for one command only, then run {{apiRun}} admin:bootstrap{{apiWorkspaceArg}}. The command creates a verified, approved admin or safely verifies an existing one.",
+    "Run all migrations to add the admin and sign-up approval columns: bun run --cwd apps/api migrate:all",
     "Remove ADMIN_BOOTSTRAP_PASSWORD from the environment after bootstrap. Keep ADMIN_EMAILS so matching future sign-ups are promoted consistently.",
     "Admin pages: /admin/users (list, approve pending registrations, ban, set role, revoke sessions). Signed-in users manage their profile, profile image, and security at /account; /admin/account remains available in the admin shell. Profile images accept PNG, JPEG, and WebP up to 2 MB and 2048 by 2048 pixels. Admin, account, authentication, maintenance, and API responses include X-Robots-Tag: noindex, nofollow by default.",
     "Password reset emails go through the mailer module (installed automatically with auth); in dev without SMTP they are logged to the API console. Configure SMTP in admin settings or via SMTP_* env for production."

package/dist/templates/modules/api-key-auth/files/apps/api/src/api-key/api-key-verifier.spec.ts

@@ -1,4 +1,4 @@
-import { afterEach, describe, expect, it } from "@jest/globals";
+import { afterEach, describe, expect, it } from "bun:test";
 import { ApiKeyVerifier } from "./api-key-verifier";
 
 const originalApiKeys = process.env.API_KEYS;

package/dist/templates/modules/api-key-auth/files/apps/api/src/api-key/api-key-verifier.ts

@@ -1,11 +1,9 @@
-import { Injectable } from "@nestjs/common";
 import { createHash, timingSafeEqual } from "node:crypto";
 
 function digest(value: string): Buffer {
   return createHash("sha256").update(value, "utf8").digest();
 }
 
-@Injectable()
 export class ApiKeyVerifier {
   private readonly keyDigests = (process.env.API_KEYS ?? "")
     .split(",")

package/dist/templates/modules/api-key-auth/files/apps/api/src/api-key/api-key.module.spec.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from "bun:test";
+import { ApiKeyVerifier } from "./api-key-verifier";
+import { requireApiKey } from "./api-key.module";
+
+describe("requireApiKey", () => {
+  it("accepts a configured key and rejects missing or invalid keys", () => {
+    const previous = process.env.API_KEYS;
+    process.env.API_KEYS = "service-key";
+    try {
+      const verifier = new ApiKeyVerifier();
+      expect(() => requireApiKey(new Headers({ "x-api-key": "service-key" }), verifier)).not.toThrow();
+      expect(() => requireApiKey(new Headers(), verifier)).toThrow("Missing X-API-Key");
+      expect(() => requireApiKey(new Headers({ "x-api-key": "invalid" }), verifier)).toThrow(
+        "Invalid API key",
+      );
+    } finally {
+      if (previous === undefined) delete process.env.API_KEYS;
+      else process.env.API_KEYS = previous;
+    }
+  });
+});

package/dist/templates/modules/api-key-auth/files/apps/api/src/api-key/api-key.module.ts

@@ -1,11 +1,38 @@
-import { Module } from "@nestjs/common";
-import { MachineController } from "../machine/machine.controller";
-import { ApiKeyGuard } from "./api-key.guard";
+import { AppException } from "@podosoft/podokit-contracts";
+import { Elysia } from "elysia";
+import {
+  ACCESS_POLICY,
+  type AppPlugin,
+  type PodokitModule,
+  type ServiceKey,
+} from "../core/services";
 import { ApiKeyVerifier } from "./api-key-verifier";
 
-@Module({
-  controllers: [MachineController],
-  providers: [ApiKeyGuard, ApiKeyVerifier],
-  exports: [ApiKeyVerifier],
-})
-export class ApiKeyModule {}
+export const API_KEY_VERIFIER = Symbol("api-key-verifier") as ServiceKey<ApiKeyVerifier>;
+
+export function requireApiKey(headers: Headers, verifier: ApiKeyVerifier): void {
+  const provided = headers.get("x-api-key");
+  if (!provided) throw new AppException("API_KEY_REQUIRED", "Missing X-API-Key", 401);
+  if (!verifier.isValid(provided)) {
+    throw new AppException("API_KEY_INVALID", "Invalid API key", 401);
+  }
+}
+
+const machinePlugin: AppPlugin = ({ services }) => {
+  const verifier = services.resolve(API_KEY_VERIFIER);
+  return new Elysia({ name: "podokit.api-key" }).get("/machine/ping", ({ request }) => {
+    requireApiKey(request.headers, verifier);
+    return { ok: true as const, via: "api-key" as const };
+  }, {
+    detail: { tags: ["machine"], summary: "Check machine API-key access" },
+  });
+};
+
+export const apiKeyModule: PodokitModule = {
+  name: "api-key-auth",
+  configure: (_env, services): void => {
+    services.register(API_KEY_VERIFIER, new ApiKeyVerifier());
+    services.resolve(ACCESS_POLICY).register("GET", "/machine/ping", "api-key");
+  },
+  plugin: machinePlugin,
+};

package/dist/templates/modules/api-key-auth/module.manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "api-key-auth",
-  "description": "API-key auth for machine/service clients (X-API-Key), separate from user sessions. Provides an ApiKeyGuard and shared ApiKeyVerifier that compare SHA-256 key digests in constant time. Requires auth.",
+  "description": "API-key auth for machine/service clients (X-API-Key), separate from user sessions. Provides an Elysia guard helper and shared constant-time ApiKeyVerifier. Requires auth.",
   "requires": ["auth"],
   "targetApp": "api",
   "env": [
@@ -8,12 +8,12 @@
     "API_KEYS=dev-key-please-change"
   ],
   "inject": [
-    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:end:imports", "text": "import { ApiKeyModule } from \"./api-key/api-key.module\";" },
-    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:end:module-imports", "text": "ApiKeyModule," }
+    { "file": "apps/api/src/app.ts", "marker": "// podokit:end:imports", "text": "import { apiKeyModule } from \"./api-key/api-key.module\";" },
+    { "file": "apps/api/src/app.ts", "marker": "// podokit:end:modules", "text": "apiKeyModule," }
   ],
   "instructions": [
     "Set API_KEYS in .env (comma-separated).",
-    "Protect a route for machine clients with @ApiKeyProtected() (bypasses the user session, requires X-API-Key).",
+    "Protect a route for machine clients with requireApiKey(request.headers, verifier).",
     "Call it:  curl -H 'x-api-key: dev-key-please-change' localhost:5002/machine/ping"
   ]
 }