@podosoft/podokit 0.17.3 → 1.0.1

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"
   ]
 }

package/dist/templates/modules/audit-log/files/apps/api/src/audit/README.md

@@ -12,20 +12,21 @@ which the better-auth hook (`audit-hook.ts`) maps to semantic action codes like
 `user.create` and `auth.login`. Everything else is **opt-in** — you decide what
 matters.
 
-## Audit your own routes with `@Audit`
+## Audit your own Elysia routes
 
 ```ts
-import { Audit } from "../audit/audit.decorator";
-
-@Post()
-@Audit("todo.create", (_req, todo) => ({ type: "todo", id: todo.id, label: todo.title }))
-create(@Body() dto: CreateTodoDto) {
-  return this.todos.create(dto);
-}
+const session = await auth.requireSession(request);
+const todo = await todos.create(body);
+await audit.recordRequest("todo.create", request, session, {
+  type: "todo",
+  id: todo.id,
+  label: todo.title,
+});
+return todo;
 ```
 
-The interceptor resolves the acting user (name + email), attaches the target you
-return, and writes one entry when the handler succeeds.
+Call `recordRequest` only after the operation succeeds. It attaches the actor and
+request address, then writes the target metadata through the shared pipeline.
 
 ## Record from anywhere in code
 
@@ -40,8 +41,8 @@ await recordAudit({
 });
 ```
 
-Or inject `AuditService` in a Nest provider and call `audit.record({ ... })`.
-Both never throw — a failed audit write never breaks the request.
+Resolve `AUDIT` from the application service registry to call
+`audit.record({ ... })`. Audit writes never break the request.
 
 ## Fields (`AuditEntry`)
 
@@ -52,8 +53,8 @@ survives renames/deletes), `targetType/targetId/targetLabel`, `ip`, `metadata`
 ## Customize
 
 - **Auth actions:** edit the `ACTIONS` map in `audit-hook.ts`.
-- **Your routes:** add `@Audit("your.action")` where you want a trail.
-- **Schema:** add columns to `audit-log.entity.ts` + a migration, and keep the
+- **Your routes:** call `AuditService.recordRequest()` after successful operations.
+- **Schema:** add columns with a migration, and keep the
   `AuditEntry` type in `audit-events.ts` in sync.
-- **Reading:** `GET /audit-logs` returns the latest 50 (admin only); extend
-  `audit.controller.ts` for filtering/pagination.
+- **Reading:** `GET /audit-logs` returns the latest 50 (admin only); extend the
+  Elysia plugin in `audit.module.ts` for filtering or pagination.

package/dist/templates/modules/audit-log/files/apps/api/src/audit/audit-events.ts

@@ -1,5 +1,5 @@
-// One audit pipeline for the whole app. Every source — the @Audit decorator, the
-// better-auth hook, and your own code — records through here, so all entries
+// One audit pipeline for the whole app. Better Auth hooks and application code
+// record through here, so all entries
 // share the actor/action/target shape and one write path (audit_logs).
 
 export type AuditEntry = {
@@ -18,11 +18,13 @@ export type AuditEntry = {
 type Recorder = (entry: AuditEntry) => Promise<void>;
 let recorder: Recorder | null = null;
 
-// AuditService registers the real recorder on startup. The registry lives outside
-// Nest's DI so code that runs outside the container (the better-auth hook,
-// background jobs, ...) can still write through the one pipeline.
-export function setAuditRecorder(fn: Recorder): void {
+// AuditService registers the recorder during Elysia configuration. The registry
+// stays available to Better Auth hooks and background jobs.
+export function setAuditRecorder(fn: Recorder): () => void {
   recorder = fn;
+  return () => {
+    if (recorder === fn) recorder = null;
+  };
 }
 
 // Record a custom audit event from anywhere. Awaits the write; a no-op until the

package/dist/templates/modules/audit-log/files/apps/api/src/audit/audit-hook.ts

@@ -3,8 +3,8 @@ import { recordAudit } from "./audit-events";
 import { auditEnabled } from "./audit-enabled";
 
 // Map mutating auth/admin endpoints to semantic action codes. better-auth is
-// mounted as middleware and bypasses the NestJS interceptor, so these security
-// events are caught here and recorded through the same pipeline.
+// mounted directly in Elysia, so these security events are recorded through the
+// same application audit pipeline.
 const ACTIONS: Record<string, string> = {
   "/sign-in/email": "auth.login",
   "/sign-up/email": "auth.signup",

package/dist/templates/modules/audit-log/files/apps/api/src/audit/audit.module.ts

@@ -1,14 +1,33 @@
-import { Module } from "@nestjs/common";
-import { APP_INTERCEPTOR } from "@nestjs/core";
-import { TypeOrmModule } from "@nestjs/typeorm";
-import { AuditController } from "./audit.controller";
-import { AuditInterceptor } from "./audit.interceptor";
+import { Elysia } from "elysia";
+import { AUTH } from "../auth/auth.module";
+import {
+  DATABASE,
+  type AppPlugin,
+  type PodokitModule,
+  type ServiceKey,
+} from "../core/services";
 import { AuditService } from "./audit.service";
-import { AuditLog } from "./audit-log.entity";
 
-@Module({
-  imports: [TypeOrmModule.forFeature([AuditLog])],
-  controllers: [AuditController],
-  providers: [AuditService, { provide: APP_INTERCEPTOR, useClass: AuditInterceptor }],
-})
-export class AuditModule {}
+export const AUDIT = Symbol("audit") as ServiceKey<AuditService>;
+
+const auditPlugin: AppPlugin = ({ services }) => {
+  const auth = services.resolve(AUTH);
+  const audit = services.resolve(AUDIT);
+  return new Elysia({ name: "podokit.audit" })
+    .get("/audit-logs", async ({ request }) => {
+      await auth.requireAdmin(request);
+      return audit.recent();
+    }, {
+      detail: { tags: ["audit"], summary: "List recent audit entries" },
+    });
+};
+
+export const auditModule: PodokitModule = {
+  name: "audit-log",
+  configure: (_env, services): void => {
+    const audit = new AuditService(services.resolve(DATABASE).sql);
+    services.register(AUDIT, audit, () => audit.close());
+    services.onStart(() => audit.connect());
+  },
+  plugin: auditPlugin,
+};

package/dist/templates/modules/audit-log/files/apps/api/src/audit/audit.service.spec.ts

@@ -0,0 +1,48 @@
+import { describe, expect, mock, test } from "bun:test";
+import type { SQL } from "bun";
+import { recordAudit } from "./audit-events";
+import { AuditService } from "./audit.service";
+
+function sqlRecorder(rows: unknown[] = []): { sql: SQL; values: unknown[][] } {
+  const values: unknown[][] = [];
+  const tag = mock((_strings: TemplateStringsArray, ...parameters: unknown[]) => {
+    values.push(parameters);
+    return Promise.resolve(rows);
+  });
+  return { sql: tag as unknown as SQL, values };
+}
+
+describe("AuditService", () => {
+  test("writes global audit events through one recorder", async () => {
+    const recorder = sqlRecorder();
+    const service = new AuditService(recorder.sql);
+    service.connect();
+    try {
+      await recordAudit({
+        action: "invoice.paid",
+        actorId: "user-1",
+        metadata: { amount: 42 },
+      });
+      expect(recorder.values).toHaveLength(1);
+      expect(recorder.values[0]).toContain("invoice.paid");
+      expect(recorder.values[0]).toContain('{"amount":42}');
+    } finally {
+      service.close();
+    }
+  });
+
+  test("returns recent entries with serialized timestamps", async () => {
+    const recorder = sqlRecorder([{
+      id: "audit-1",
+      action: "auth.login",
+      createdAt: new Date("2026-01-02T03:04:05.000Z"),
+    }]);
+    const entries = await new AuditService(recorder.sql).recent();
+    expect(entries[0]?.createdAt).toBe("2026-01-02T03:04:05.000Z");
+  });
+
+  test("does not propagate persistence failures", async () => {
+    const sql = mock(() => Promise.reject(new Error("database unavailable"))) as unknown as SQL;
+    await expect(new AuditService(sql).record({ action: "auth.login" })).resolves.toBeUndefined();
+  });
+});

package/dist/templates/modules/audit-log/files/apps/api/src/audit/audit.service.ts

@@ -1,36 +1,87 @@
-import { Injectable, type OnModuleInit } from "@nestjs/common";
-import { InjectRepository } from "@nestjs/typeorm";
-import { Repository } from "typeorm";
-import { AuditLog } from "./audit-log.entity";
+import type { SQL } from "bun";
+import type { AuthSession } from "../auth/auth.service";
+import { auditEnabled } from "./audit-enabled";
 import { setAuditRecorder, type AuditEntry } from "./audit-events";
 
-// The one place audit entries are written. Inject it to record from Nest code,
-// or call recordAudit() from anywhere else — both end up here.
-@Injectable()
-export class AuditService implements OnModuleInit {
-  constructor(@InjectRepository(AuditLog) private readonly logs: Repository<AuditLog>) {}
+export interface AuditLogView extends AuditEntry {
+  id: string;
+  createdAt: string;
+}
+
+interface AuditLogRow extends Omit<AuditLogView, "createdAt"> {
+  createdAt: Date;
+}
+
+export interface AuditTarget {
+  type?: string;
+  id?: string;
+  label?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export class AuditService {
+  private unregister?: () => void;
+
+  constructor(private readonly sql: SQL) {}
 
-  onModuleInit(): void {
-    setAuditRecorder((entry) => this.record(entry));
+  connect(): void {
+    this.unregister ??= setAuditRecorder((entry) => this.record(entry));
+  }
+
+  close(): void {
+    this.unregister?.();
+    this.unregister = undefined;
   }
 
   async record(entry: AuditEntry): Promise<void> {
     try {
-      await this.logs.save(
-        this.logs.create({
-          action: entry.action,
-          actorId: entry.actorId ?? null,
-          actorName: entry.actorName ?? null,
-          actorEmail: entry.actorEmail ?? null,
-          targetType: entry.targetType ?? null,
-          targetId: entry.targetId ?? null,
-          targetLabel: entry.targetLabel ?? null,
-          ip: entry.ip ?? null,
-          metadata: entry.metadata ?? null,
-        }),
-      );
+      const metadata = entry.metadata === undefined || entry.metadata === null
+        ? null
+        : JSON.stringify(entry.metadata);
+      await this.sql`
+        INSERT INTO "audit_logs" (
+          "action", "actorId", "actorName", "actorEmail",
+          "targetType", "targetId", "targetLabel", "ip", "metadata"
+        ) VALUES (
+          ${entry.action}, ${entry.actorId ?? null}, ${entry.actorName ?? null},
+          ${entry.actorEmail ?? null}, ${entry.targetType ?? null},
+          ${entry.targetId ?? null}, ${entry.targetLabel ?? null}, ${entry.ip ?? null},
+          ${metadata}::jsonb
+        )
+      `;
     } catch {
-      // An audit write must never break the request it describes.
+      // Audit persistence must never break the operation it describes.
     }
   }
+
+  async recent(limit = 50): Promise<AuditLogView[]> {
+    const rows = await this.sql<AuditLogRow[]>`
+      SELECT "id", "action", "actorId", "actorName", "actorEmail",
+             "targetType", "targetId", "targetLabel", "ip", "metadata", "createdAt"
+      FROM "audit_logs"
+      ORDER BY "createdAt" DESC
+      LIMIT ${limit}
+    `;
+    return rows.map((row) => ({ ...row, createdAt: row.createdAt.toISOString() }));
+  }
+
+  async recordRequest(
+    action: string,
+    request: Request,
+    session: AuthSession,
+    target: AuditTarget = {},
+  ): Promise<void> {
+    if (!(await auditEnabled())) return;
+    await this.record({
+      action,
+      actorId: session.user.id,
+      actorName: typeof session.user.name === "string" ? session.user.name : null,
+      actorEmail: typeof session.user.email === "string" ? session.user.email : null,
+      targetType: target.type ?? null,
+      targetId: target.id ?? null,
+      targetLabel: target.label ?? null,
+      metadata: target.metadata ?? null,
+      ip: request.headers.get("x-forwarded-for") ?? null,
+    });
+  }
 }

package/dist/templates/modules/audit-log/module.manifest.json

@@ -1,27 +1,23 @@
 {
   "name": "audit-log",
-  "description": "Audit logging: records who did each mutating request (who/method/path/status) to an audit_logs table \u2014 a NestJS interceptor for your own API routes plus a better-auth hook for auth/admin actions (login, ban, role changes, ...). Requires auth.",
-  "requires": [
-    "auth"
-  ],
+  "description": "Audit logging for Elysia and Better Auth: stores semantic actor/action/target events in audit_logs, including login, ban, role, session, and user lifecycle actions. Requires auth.",
+  "requires": ["auth"],
   "targetApp": "api",
   "env": [
-    "# audit-log: on/off is managed on the admin Settings page (stored in the DB,",
-    "# applied live, no restart). This env var is the fallback default used until an",
-    "# admin sets it \u2014 leave it 'true' so the trail is on out of the box; the DB value",
-    "# (Settings page) overrides it once set.",
+    "# audit-log: managed on the admin Settings page, stored in the DB,",
+    "# and applied without restart. This environment value is the fallback.",
     "AUDIT_LOG_ENABLED=true"
   ],
   "inject": [
     {
-      "file": "apps/api/src/app.module.ts",
+      "file": "apps/api/src/app.ts",
       "marker": "// podokit:end:imports",
-      "text": "import { AuditModule } from \"./audit/audit.module\";"
+      "text": "import { auditModule } from \"./audit/audit.module\";"
     },
     {
-      "file": "apps/api/src/app.module.ts",
-      "marker": "// podokit:end:module-imports",
-      "text": "AuditModule,"
+      "file": "apps/api/src/app.ts",
+      "marker": "// podokit:end:modules",
+      "text": "auditModule,"
     },
     {
       "file": "apps/api/src/auth/auth.ts",
@@ -35,9 +31,9 @@
     }
   ],
   "instructions": [
-    "Run migrations to create the audit_logs table:  npm run migration:run -w <app>-api",
-    "Auth/admin actions (login, ban, role changes, session revocation, user CRUD) are recorded via a better-auth hook; your own mutating NestJS routes are recorded by the interceptor.",
-    "List recent entries (admin session required):  curl -b cookies.txt localhost:5002/audit-logs"
+    "Run migrations to create the audit_logs table: {{apiRun}} migration:run{{apiWorkspaceArg}}",
+    "Auth/admin actions are recorded by a Better Auth hook. Record semantic application events with AuditService.recordRequest() or recordAudit().",
+    "List recent entries (admin session required): curl -b cookies.txt localhost:5002/audit-logs"
   ],
   "dependencies": {
     "@podosoft/podokit-auth": "^0.3.0"

package/dist/templates/modules/auth/files/apps/api/scripts/configure-auth.mjs

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env bun
 
 const args = process.argv.slice(2);
 
@@ -15,10 +15,10 @@ function usage() {
   console.log(`Configure PodoKit authentication through the admin API.
 
 Usage:
-  npm run auth:configure -- --provider google --require-signup-approval
-  npm run auth:configure -- --provider google --redirect-only
-  npm run auth:configure -- --smtp
-  npm run auth:configure -- --check-only --provider google
+  {{apiRun}} auth:configure -- --provider google --require-signup-approval
+  {{apiRun}} auth:configure -- --provider google --redirect-only
+  {{apiRun}} auth:configure -- --smtp
+  {{apiRun}} auth:configure -- --check-only --provider google
 
 Required environment for writes:
   AUTH_SETUP_ORIGIN          Public app origin (or BETTER_AUTH_URL)

package/dist/templates/modules/auth/files/apps/api/scripts/run-migrations.mjs

@@ -0,0 +1,14 @@
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const compiledEntry = new URL("../dist/migrate.js", import.meta.url);
+const sourceEntry = new URL("../src/migrate.ts", import.meta.url);
+const useCompiled = process.env.NODE_ENV === "production" && existsSync(compiledEntry);
+const entry = useCompiled ? compiledEntry : sourceEntry;
+const subprocess = Bun.spawn([process.execPath, fileURLToPath(entry)], {
+  stdin: "inherit",
+  stdout: "inherit",
+  stderr: "inherit",
+});
+
+process.exitCode = await subprocess.exited;

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

@@ -4,12 +4,9 @@ import { authConfigStore } from "./auth-config-store";
 // Runtime auth instance that rebuilds when the DB config changes, so admin edits
 // (OAuth credentials, SMTP, server-enforced toggles) apply WITHOUT a restart.
 //
-// @thallesp/nestjs-better-auth reads `auth.handler` exactly once (via toNodeHandler)
-// and `auth.api` per request. We hand it a Proxy: `.handler` is a STABLE delegating
-// function (so the adapter's captured reference stays valid) that redispatches each
-// request to the currently-built instance; every other access forwards to the
-// current instance too. The guard/session behavior is unchanged (session tokens are
-// signed with the stable BETTER_AUTH_SECRET; trustedOrigins is baked into every build).
+// Elysia mounts `auth.handler` once. The proxy exposes a stable delegating handler
+// that refreshes the DB-backed configuration and dispatches to the current Better
+// Auth instance. Session tokens remain valid because BETTER_AUTH_SECRET is stable.
 
 const TTL_MS = 3_000;