@rebasepro/server-core 0.6.0 → 0.7.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/server-core",
   "type": "module",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Database-Agnostic Backend Core for Rebase",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -30,6 +30,13 @@
     "backend",
     "database"
   ],
+  "scripts": {
+    "watch": "vite build --watch",
+    "build": "vite build && tsc --emitDeclarationOnly -p tsconfig.prod.json",
+    "test:lint": "eslint \"src/**\" --quiet",
+    "test": "cross-env NODE_OPTIONS=\"--experimental-vm-modules\" jest --passWithNoTests --forceExit",
+    "clean": "rm -rf dist && find ./src -name '*.js' -type f | xargs rm -f"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -44,6 +51,10 @@
     "@aws-sdk/s3-request-presigner": "^3.1068.0",
     "@hono/graphql-server": "0.7.0",
     "@hono/node-server": "2.0.4",
+    "@rebasepro/client": "workspace:*",
+    "@rebasepro/common": "workspace:*",
+    "@rebasepro/types": "workspace:*",
+    "@rebasepro/utils": "workspace:*",
     "drizzle-orm": "^0.45.2",
     "google-auth-library": "^10.7.0",
     "graphql": "^16.14.2",
@@ -53,11 +64,7 @@
     "sharp": "^0.35.1",
     "ts-morph": "28.0.0",
     "ws": "^8.21.0",
-    "zod": "^4.4.3",
-    "@rebasepro/client": "0.6.0",
-    "@rebasepro/common": "0.6.0",
-    "@rebasepro/utils": "0.6.0",
-    "@rebasepro/types": "0.6.0"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",
@@ -77,12 +84,5 @@
   "gitHead": "d935eefa5aa8d1009a2398cfac2c1e4ee9aeb6b6",
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {
-    "watch": "vite build --watch",
-    "build": "vite build && tsc --emitDeclarationOnly -p tsconfig.prod.json",
-    "test:lint": "eslint \"src/**\" --quiet",
-    "test": "cross-env NODE_OPTIONS=\"--experimental-vm-modules\" jest --passWithNoTests --forceExit",
-    "clean": "rm -rf dist && find ./src -name '*.js' -type f | xargs rm -f"
   }
-}
+}

package/src/api/errors.ts

@@ -145,12 +145,26 @@ export const errorHandler: ErrorHandler<HonoEnv> = (err, c) => {
 
     // Handle DB connection and specific system errors for better logging
     let logMessage = error.message;
+
+    // Resolve the actual cause — Node's net module wraps dual-stack failures
+    // in an AggregateError whose inner errors carry the real address/port.
+    let resolvedCause: PgLikeError | undefined;
     if (error.cause && typeof error.cause === "object" && error.cause !== null && "code" in error.cause) {
-        const cause = error.cause as PgLikeError;
+        const cause = error.cause as PgLikeError & { errors?: PgLikeError[] };
+        if (cause.code === "ECONNREFUSED" && !cause.address && Array.isArray(cause.errors)) {
+            // AggregateError — pick the first inner error that has address info
+            resolvedCause = cause.errors.find(e => e.address) || cause;
+        } else {
+            resolvedCause = cause;
+        }
+    }
+
+    if (resolvedCause) {
+        const cause = resolvedCause;
         if (cause.code === "ENETUNREACH") {
             logMessage = `Network unreachable. Cannot connect to database at ${cause.address}:${cause.port}.`;
         } else if (cause.code === "ECONNREFUSED") {
-            logMessage = `Connection refused to database at ${cause.address}:${cause.port}.`;
+            logMessage = `Connection refused to database at ${cause.address}:${cause.port}. Is PostgreSQL running?`;
         } else if (cause.code === "42703" || cause.code === "42P01") {
             code = "SCHEMA_DRIFT";
             const issue = cause.code === "42703" ? "column" : "table";

package/src/api/graphql/graphql-schema-generator.ts

@@ -12,6 +12,14 @@ import {
     GraphQLInputFieldConfig
 } from "graphql";
 import { DataDriver, EntityCollection, FetchCollectionProps, Property, Entity } from "@rebasepro/types";
+import { isOperationAllowed, type ApiKeyOperation } from "../../auth/api-keys/api-key-permission-guard";
+import type { ApiKeyMasked } from "../../auth/api-keys/api-key-types";
+
+/** Context shape provided by @hono/graphql-server (Hono's Context object). */
+type GraphQLResolverContext = {
+    get?: (key: string) => unknown;
+    driver?: DataDriver;
+};
 
 /**
  * Lightweight GraphQL schema generator that leverages existing DataDriver
@@ -28,6 +36,28 @@ export class GraphQLSchemaGenerator {
         this.driver = driver;
     }
 
+    /**
+     * Enforce API key permission scoping for a GraphQL resolver.
+     *
+     * Extracts the `apiKey` from the Hono context passed by `@hono/graphql-server`.
+     * If the request was made with an API key and the key does not have the
+     * required permission for the target collection/operation, an error is thrown.
+     * Non-API-key requests (e.g. session auth) are allowed through.
+     */
+    private enforceApiKeyPermission(
+        context: GraphQLResolverContext | undefined,
+        collectionSlug: string,
+        operation: ApiKeyOperation
+    ): void {
+        const apiKey = context?.get?.("apiKey") as ApiKeyMasked | undefined;
+        if (!apiKey) return;
+        if (!isOperationAllowed(apiKey.permissions, collectionSlug, operation)) {
+            throw new Error(
+                `API key does not have "${operation}" permission for collection "${collectionSlug}"`
+            );
+        }
+    }
+
     /**
      * Generate complete GraphQL schema using existing DataDriver
      */
@@ -184,8 +214,9 @@ export class GraphQLSchemaGenerator {
                     id: { type: new GraphQLNonNull(GraphQLString) }
                 },
                 resolve: async (_, args, context: unknown) => {
-                    const ctx = context as { driver?: DataDriver } | undefined;
-                    const ds = ctx?.driver;
+                    const ctx = context as GraphQLResolverContext | undefined;
+                    this.enforceApiKeyPermission(ctx, collection.slug, "read");
+                    const ds = ctx?.get?.("driver") as DataDriver | undefined ?? (ctx as Record<string, unknown> | undefined)?.driver as DataDriver | undefined;
                     if (!ds) throw new Error("Scoped driver not available");
                     const entity = await ds.fetchEntity({
                         path: collection.slug,
@@ -208,8 +239,9 @@ defaultValue: 0 },
                     orderBy: { type: GraphQLString }
                 },
                 resolve: async (_, args, context: unknown) => {
-                    const ctx = context as { driver?: DataDriver } | undefined;
-                    const ds = ctx?.driver;
+                    const ctx = context as GraphQLResolverContext | undefined;
+                    this.enforceApiKeyPermission(ctx, collection.slug, "read");
+                    const ds = ctx?.get?.("driver") as DataDriver | undefined ?? (ctx as Record<string, unknown> | undefined)?.driver as DataDriver | undefined;
                     if (!ds) throw new Error("Scoped driver not available");
                     let filter: FetchCollectionProps["filter"] | undefined;
                     if (args.where) {
@@ -261,8 +293,9 @@ defaultValue: 0 },
                     input: { type: new GraphQLNonNull(inputType) }
                 },
                 resolve: async (_, args, context: unknown) => {
-                    const ctx = context as { driver?: DataDriver } | undefined;
-                    const ds = ctx?.driver;
+                    const ctx = context as GraphQLResolverContext | undefined;
+                    this.enforceApiKeyPermission(ctx, collection.slug, "write");
+                    const ds = ctx?.get?.("driver") as DataDriver | undefined ?? (ctx as Record<string, unknown> | undefined)?.driver as DataDriver | undefined;
                     if (!ds) throw new Error("Scoped driver not available");
                     const path = collection.slug;
                     const entity = await ds.saveEntity({
@@ -283,8 +316,9 @@ defaultValue: 0 },
                     input: { type: new GraphQLNonNull(inputType) }
                 },
                 resolve: async (_, args, context: unknown) => {
-                    const ctx = context as { driver?: DataDriver } | undefined;
-                    const ds = ctx?.driver;
+                    const ctx = context as GraphQLResolverContext | undefined;
+                    this.enforceApiKeyPermission(ctx, collection.slug, "write");
+                    const ds = ctx?.get?.("driver") as DataDriver | undefined ?? (ctx as Record<string, unknown> | undefined)?.driver as DataDriver | undefined;
                     if (!ds) throw new Error("Scoped driver not available");
                     const entity = await ds.saveEntity({
                         path: collection.slug,
@@ -304,9 +338,10 @@ defaultValue: 0 },
                     id: { type: new GraphQLNonNull(GraphQLString) }
                 },
                 resolve: async (_, args, context: unknown) => {
+                    const ctx = context as GraphQLResolverContext | undefined;
+                    this.enforceApiKeyPermission(ctx, collection.slug, "delete");
                     try {
-                        const ctx = context as { driver?: DataDriver } | undefined;
-                        const ds = ctx?.driver;
+                        const ds = ctx?.get?.("driver") as DataDriver | undefined ?? (ctx as Record<string, unknown> | undefined)?.driver as DataDriver | undefined;
                         if (!ds) throw new Error("Scoped driver not available");
                         const existingEntity = await ds.fetchEntity({
                             path: collection.slug,

package/src/api/rest/api-generator.ts

@@ -294,7 +294,16 @@ values: entity.values as Record<string, unknown> },
                 return c.json(response, 201);
             } catch (error) {
                 if (isRebaseApiError(error) && !error.code) {
-                    error.code = "BAD_REQUEST";
+                    // Only classify as BAD_REQUEST if it's an operational error
+                    // (e.g. validation, DB constraints). Runtime bugs like TypeError,
+                    // RangeError etc. should remain as 500 INTERNAL_ERROR.
+                    const isRuntimeBug = error instanceof TypeError
+                        || error instanceof RangeError
+                        || error instanceof SyntaxError
+                        || error instanceof ReferenceError;
+                    if (!isRuntimeBug) {
+                        error.code = "BAD_REQUEST";
+                    }
                 }
                 throw error;
             }
@@ -343,7 +352,15 @@ values: entity.values as Record<string, unknown> },
                 return c.json(response);
             } catch (error) {
                 if (isRebaseApiError(error) && !error.code) {
-                    error.code = "BAD_REQUEST";
+                    // Only classify as BAD_REQUEST if it's an operational error.
+                    // Runtime bugs (TypeError, RangeError, etc.) stay as 500.
+                    const isRuntimeBug = error instanceof TypeError
+                        || error instanceof RangeError
+                        || error instanceof SyntaxError
+                        || error instanceof ReferenceError;
+                    if (!isRuntimeBug) {
+                        error.code = "BAD_REQUEST";
+                    }
                 }
                 throw error;
             }

package/src/api/server.ts

@@ -6,6 +6,7 @@ import { serve } from "@hono/node-server";
 import { GraphQLSchemaGenerator } from "./graphql/graphql-schema-generator";
 import { RestApiGenerator } from "./rest/api-generator";
 import { DataDriver, EntityCollection, Relation } from "@rebasepro/types";
+import { createDataSourceRegistry, resolveDataSource } from "@rebasepro/common";
 import { ApiConfig, HonoEnv } from "./types";
 import { loadCollectionsFromDirectory } from "../collections/loader";
 import { createSchemaEditorRoutes } from "./schema-editor-routes";
@@ -142,9 +143,16 @@ export class RebaseApiServer {
             return c.json({ data: collectionsMetadata });
         });
 
+        // Server data routes are only generated for server-transport
+        // collections; direct/custom sources are client-only.
+        const dataSourceRegistry = createDataSourceRegistry(this.config.dataSources);
+        const serverCollections = (this.config.collections || []).filter(
+            (collection) => resolveDataSource(collection, dataSourceRegistry).transport === "server"
+        );
+
         // GraphQL endpoint
         if (this.config.enableGraphQL) {
-            const schemaGenerator = new GraphQLSchemaGenerator(this.config.collections || [], this.driver);
+            const schemaGenerator = new GraphQLSchemaGenerator(serverCollections, this.driver);
             const schema = schemaGenerator.generateSchema();
 
             // Context is automatically passed to resolvers via contextValue containing Hono's 'c'
@@ -182,7 +190,7 @@ export class RebaseApiServer {
         }
 
         if (this.config.enableREST) {
-            const restGenerator = new RestApiGenerator(this.config.collections || [], this.driver);
+            const restGenerator = new RestApiGenerator(serverCollections, this.driver);
             const restRoutes = restGenerator.generateRoutes();
             this.router.route(basePath, restRoutes);
         }

package/src/api/types.ts

@@ -28,6 +28,12 @@ export type HonoEnv = {
 export interface ApiConfig {
     collections?: EntityCollection[];
     collectionsDir?: string;
+    /**
+     * Declared data sources. When provided, collections on a `direct`/`custom`
+     * transport are treated as client-only and no server routes are generated
+     * for them.
+     */
+    dataSources?: import("@rebasepro/types").DataSourceDefinition[];
     basePath?: string;
     enableGraphQL?: boolean;
     enableREST?: boolean;

package/src/auth/adapter-middleware.ts

@@ -15,7 +15,7 @@
  * token verification strategy is pluggable.
  */
 
-import type { MiddlewareHandler } from "hono";
+import type { MiddlewareHandler, Context } from "hono";
 import type { DataDriver, AuthAdapter } from "@rebasepro/types";
 import type { HonoEnv } from "../api/types";
 import type { ApiKeyStore } from "./api-keys/api-key-store";
@@ -28,6 +28,12 @@ export interface AdapterAuthMiddlewareOptions {
     adapter: AuthAdapter;
     /** The DataDriver to scope via withAuth() for RLS. */
     driver: DataDriver;
+    /**
+     * Optional per-request driver resolver for multi-data-source backends.
+     * Returns the unscoped delegate to use for this request (e.g. Postgres vs
+     * Mongo). When omitted, `driver` is used for every request.
+     */
+    resolveDriver?: (c: Context<HonoEnv>) => DataDriver;
     /**
      * If true, return 401 when no valid user is resolved.
      * Defaults to `true` (secure by default).
@@ -41,9 +47,11 @@ export interface AdapterAuthMiddlewareOptions {
  * Create a Hono middleware that uses an `AuthAdapter` for request verification.
  */
 export function createAdapterAuthMiddleware(options: AdapterAuthMiddlewareOptions): MiddlewareHandler<HonoEnv> {
-    const { adapter, driver, requireAuth: enforceAuth = true, apiKeyStore } = options;
+    const { adapter, driver: baseDriver, resolveDriver, requireAuth: enforceAuth = true, apiKeyStore } = options;
 
     return async (c, next) => {
+        // Pick the per-request delegate (multi-data-source) before scoping.
+        const driver = resolveDriver ? resolveDriver(c) : baseDriver;
         // ── API Key check (Rebase-level, independent of auth adapter) ────
         if (apiKeyStore) {
             const authHeader = c.req.header("authorization") || "";

package/src/auth/admin-roles-route.ts

@@ -0,0 +1,36 @@
+/**
+ * Admin endpoint for listing all roles.
+ *
+ * Mounts: GET /roles
+ */
+
+import { Hono } from "hono";
+import { errorHandler } from "../api/errors";
+import type { AuthRepository } from "./interfaces";
+import { createRequireAuth, requireAdmin } from "./middleware";
+import type { HonoEnv } from "../api/types";
+
+export interface AdminRolesRouteConfig {
+    authRepo: AuthRepository;
+    serviceKey?: string;
+}
+
+/**
+ * Create a standalone admin route for listing roles.
+ *
+ * Mounts: GET /roles
+ */
+export function createAdminRolesRoute(config: AdminRolesRouteConfig): Hono<HonoEnv> {
+    const router = new Hono<HonoEnv>();
+    const authRepo = config.authRepo;
+
+    router.onError(errorHandler);
+    router.use("/*", createRequireAuth({ serviceKey: config.serviceKey }));
+
+    router.get("/roles", requireAdmin, async (c) => {
+        const roles = await authRepo.listRoles();
+        return c.json({ roles });
+    });
+
+    return router;
+}

package/src/auth/admin-users-route.ts

@@ -0,0 +1,302 @@
+/**
+ * Standalone admin endpoint for user management.
+ *
+ * Mounts:
+ *   GET /users
+ *   GET /users/:userId
+ *   POST /users
+ *   PUT /users/:userId
+ *   DELETE /users/:userId
+ *   POST /bootstrap
+ */
+
+import { Hono } from "hono";
+import { ApiError, errorHandler } from "../api/errors";
+import type { AuthRepository } from "./interfaces";
+import { createRequireAuth, requireAdmin } from "./middleware";
+import type { AuthHooks } from "./auth-hooks";
+import { resolveAuthHooks } from "./auth-hooks";
+import { prepareAdminUserValues, finalizeAdminUserCreation } from "./admin-user-ops";
+import type { EmailService, EmailConfig } from "../email";
+import type { HonoEnv } from "../api/types";
+import type { AdminUser, AuthCollectionConfig } from "@rebasepro/types";
+import { logger } from "../utils/logger";
+
+export interface AdminUsersRouteConfig {
+    authRepo: AuthRepository;
+    emailService?: EmailService;
+    emailConfig?: EmailConfig;
+    serviceKey?: string;
+    authHooks?: AuthHooks;
+    collectionAuthConfig?: AuthCollectionConfig;
+    isBootstrapCompleted?: () => Promise<boolean>;
+    setBootstrapCompleted?: () => Promise<void>;
+}
+
+export function createAdminUsersRoute(config: AdminUsersRouteConfig): Hono<HonoEnv> {
+    const router = new Hono<HonoEnv>();
+    const authRepo = config.authRepo;
+    const { emailService, emailConfig, collectionAuthConfig } = config;
+    const ops = resolveAuthHooks(config.authHooks);
+
+    function toAdminUser(
+        u: {
+            id: string;
+            email: string;
+            displayName?: string | null;
+            photoUrl?: string | null;
+            createdAt?: Date | string;
+            updatedAt?: Date | string;
+        },
+        roles: string[]
+    ): AdminUser {
+        return {
+            uid: u.id,
+            email: u.email,
+            displayName: u.displayName ?? null,
+            photoURL: u.photoUrl ?? null,
+            provider: "custom",
+            roles,
+            createdAt: u.createdAt instanceof Date ? u.createdAt.toISOString() : (u.createdAt ?? new Date().toISOString()),
+            updatedAt: u.updatedAt instanceof Date ? u.updatedAt.toISOString() : (u.updatedAt ?? new Date().toISOString())
+        };
+    }
+
+    router.onError(errorHandler);
+    router.use("/*", createRequireAuth({ serviceKey: config.serviceKey }));
+
+    router.post("/bootstrap", async (c) => {
+        const user = c.get("user");
+        if (!user || typeof user !== "object") {
+            throw ApiError.unauthorized("Not authenticated");
+        }
+
+        if (config.isBootstrapCompleted) {
+            const alreadyDone = await config.isBootstrapCompleted();
+            if (alreadyDone) {
+                throw ApiError.forbidden("Bootstrap has already been completed.", "BOOTSTRAP_COMPLETED");
+            }
+        }
+
+        const users = await authRepo.listUsers();
+        let hasAdmin = false;
+
+        for (const u of users) {
+            const roles = await authRepo.getUserRoleIds(u.id);
+            if (roles.includes("admin")) {
+                hasAdmin = true;
+                break;
+            }
+        }
+
+        if (hasAdmin) {
+            throw ApiError.forbidden("Admin users already exist. Bootstrap not allowed.", "BOOTSTRAP_COMPLETED");
+        }
+
+        const userId = "userId" in user ? (user as { userId: string }).userId : ("uid" in user ? (user as { uid: string }).uid : undefined);
+        if (!userId) {
+            throw ApiError.unauthorized("User ID not found in auth context");
+        }
+        const caller = await authRepo.getUserById(userId);
+        if (!caller) {
+            throw ApiError.notFound("Authenticated user does not exist in the database.", "USER_NOT_FOUND");
+        }
+        await authRepo.setUserRoles(userId, ["admin"]);
+
+        if (config.setBootstrapCompleted) {
+            await config.setBootstrapCompleted();
+        }
+
+        return c.json({
+            success: true,
+            message: "You are now an admin",
+            user: {
+                uid: userId,
+                roles: ["admin"]
+            }
+        });
+    });
+
+    router.get("/users", requireAdmin, async (c) => {
+        const limitParam = c.req.query("limit");
+        const offsetParam = c.req.query("offset");
+        const search = c.req.query("search");
+        const orderBy = c.req.query("orderBy");
+        const orderDir = c.req.query("orderDir") as "asc" | "desc" | undefined;
+
+        const limit = limitParam ? parseInt(limitParam, 10) : 25;
+        const offset = offsetParam ? parseInt(offsetParam, 10) : 0;
+
+        const result = await authRepo.listUsersPaginated({
+            limit,
+            offset,
+            search: search || undefined,
+            orderBy: orderBy || undefined,
+            orderDir: orderDir || undefined,
+            roleId: c.req.query("role") || undefined
+        });
+
+        const usersWithRoles = await Promise.all(
+            result.users.map(async (u) => {
+                const roles = await authRepo.getUserRoleIds(u.id);
+                return toAdminUser(u, roles);
+            })
+        );
+
+        return c.json({
+            users: usersWithRoles,
+            total: result.total,
+            limit: result.limit,
+            offset: result.offset
+        });
+    });
+
+    router.get("/users/:userId", requireAdmin, async (c) => {
+        const userId = c.req.param("userId");
+        const result = await authRepo.getUserWithRoles(userId);
+
+        if (!result) {
+            throw ApiError.notFound("User not found");
+        }
+
+        const adminUser = toAdminUser(result.user, result.roles.map((r) => r.id));
+        return c.json({ user: adminUser });
+    });
+
+    router.post("/users", requireAdmin, async (c) => {
+        const body = await c.req.json();
+        const { email, roles } = body;
+        if (!email) {
+            throw ApiError.badRequest("Email is required");
+        }
+
+        const existing = await authRepo.getUserByEmail(email.toLowerCase());
+        if (existing) {
+            throw ApiError.conflict("A user with this email already exists");
+        }
+
+        const prepResult = await prepareAdminUserValues(body, {
+            authRepo,
+            emailService,
+            emailConfig,
+            resolvedHooks: ops,
+            collectionAuthConfig
+        });
+
+        const user = await authRepo.createUser({
+            email: prepResult.values.email as string,
+            passwordHash: prepResult.values.passwordHash as string | undefined,
+            displayName: prepResult.values.displayName as string | undefined,
+            photoUrl: prepResult.values.photoUrl as string | undefined,
+            metadata: prepResult.values.metadata as Record<string, unknown> | undefined
+        });
+
+        if (roles && Array.isArray(roles)) {
+            await authRepo.setUserRoles(user.id, roles);
+        }
+
+        const finalizeResult = await finalizeAdminUserCreation(
+            { id: user.id, values: prepResult.values },
+            prepResult.clearPassword,
+            {
+                authRepo,
+                emailService,
+                emailConfig,
+                resolvedHooks: ops,
+                collectionAuthConfig
+            }
+        );
+
+        const userRoles = await authRepo.getUserRoleIds(user.id);
+        const adminUser = toAdminUser(user, userRoles);
+
+        return c.json(
+            {
+                user: adminUser,
+                invitationSent: finalizeResult.invitationSent,
+                ...(finalizeResult.temporaryPassword ? { temporaryPassword: finalizeResult.temporaryPassword } : {})
+            },
+            201
+        );
+    });
+
+    router.put("/users/:userId", requireAdmin, async (c) => {
+        const userId = c.req.param("userId");
+        const body = await c.req.json();
+        const { password, email, displayName, roles } = body;
+
+        const existing = await authRepo.getUserById(userId);
+        if (!existing) {
+            throw ApiError.notFound("User not found");
+        }
+
+        const updates: Record<string, unknown> = {};
+        if (email !== undefined) updates.email = email.toLowerCase();
+        if (displayName !== undefined) updates.displayName = displayName;
+
+        if (password) {
+            const validation = ops.validatePasswordStrength(password);
+            if (!validation.valid) {
+                throw ApiError.badRequest(`Password too weak: ${validation.errors.join(". ")}`);
+            }
+            updates.passwordHash = await ops.hashPassword(password);
+        }
+
+        if (Object.keys(updates).length > 0) {
+            await authRepo.updateUser(userId, updates);
+        }
+
+        if (roles !== undefined && Array.isArray(roles)) {
+            const currentRoles = await authRepo.getUserRoleIds(userId);
+            const wasAdmin = currentRoles.includes("admin");
+            const willBeAdmin = roles.includes("admin");
+
+            if (wasAdmin && !willBeAdmin) {
+                const adminUsers = await authRepo.listUsersPaginated({
+                    roleId: "admin",
+                    limit: 1
+                });
+                if (adminUsers.total <= 1) {
+                    throw ApiError.forbidden("Cannot demote the last administrator", "LAST_ADMIN");
+                }
+            }
+            await authRepo.setUserRoles(userId, roles);
+        }
+
+        const result = await authRepo.getUserWithRoles(userId);
+        const adminUser = toAdminUser(result!.user, result!.roles.map((r) => r.id));
+
+        return c.json({ user: adminUser });
+    });
+
+    router.delete("/users/:userId", requireAdmin, async (c) => {
+        const userId = c.req.param("userId");
+        const authUser = c.get("user") as { uid?: string; userId?: string } | undefined;
+        const currentUserId = authUser?.uid || authUser?.userId;
+
+        if (currentUserId === userId) {
+            throw ApiError.badRequest("Cannot delete your own account", "SELF_DELETE");
+        }
+
+        const existing = await authRepo.getUserById(userId);
+        if (!existing) {
+            throw ApiError.notFound("User not found");
+        }
+
+        const roles = await authRepo.getUserRoleIds(userId);
+        if (roles.includes("admin")) {
+            const adminUsers = await authRepo.listUsersPaginated({
+                roleId: "admin",
+                limit: 1
+            });
+            if (adminUsers.total <= 1) {
+                throw ApiError.forbidden("Cannot delete the last administrator", "LAST_ADMIN");
+            }
+        }
+
+        await authRepo.deleteUser(userId);
+        return c.json({ success: true });
+    });
+
+    return router;
+}