@rebasepro/server-core 0.2.3 → 0.3.0

package/src/auth/admin-routes.ts

@@ -2,8 +2,8 @@ import { Hono } from "hono";
 import { ApiError, errorHandler } from "../api/errors";
 import type { AuthRepository } from "./interfaces";
 import { requireAuth, requireAdmin, createRequireAuth } from "./middleware";
-import type { AuthOverrides } from "./auth-overrides";
-import { resolveAuthOverrides } from "./auth-overrides";
+import type { AuthHooks } from "./auth-hooks";
+import { resolveAuthHooks } from "./auth-hooks";
 import { AuthModuleConfig } from "./routes";
 import type { BackendHooks, AdminUser, AdminRole, BackendHookContext } from "@rebasepro/types";
 
@@ -19,10 +19,10 @@ interface AdminRouteOptions extends AuthModuleConfig {
      */
     hooks?: BackendHooks;
     /**
-     * Auth overrides for customizing password hashing, credential
+     * Auth hooks for customizing password hashing, credential
      * verification, lifecycle hooks, etc.
      */
-    overrides?: AuthOverrides;
+    authHooks?: AuthHooks;
 }
 import { HonoEnv } from "../api/types";
 import { randomBytes, createHash } from "crypto";
@@ -74,8 +74,8 @@ function hashToken(token: string): string {
 export function createAdminRoutes(config: AdminRouteOptions): Hono<HonoEnv> {
     const router = new Hono<HonoEnv>();
     const authRepo = config.authRepo;
-    const { emailService, emailConfig, hooks, overrides } = config;
-    const ops = resolveAuthOverrides(overrides);
+    const { emailService, emailConfig, hooks, authHooks } = config;
+    const ops = resolveAuthHooks(authHooks);
 
     /** Build a BackendHookContext from Hono's context object */
     function buildHookContext(c: { get: (key: string) => unknown }, method: BackendHookContext["method"]): BackendHookContext {
@@ -174,6 +174,10 @@ export function createAdminRoutes(config: AdminRouteOptions): Hono<HonoEnv> {
         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. Please sign out and sign in/register again.", "USER_NOT_FOUND");
+        }
         await authRepo.setUserRoles(userId, ["admin"]);
 
         // ── Set persistent flag ──────────────────────────────────────
@@ -456,6 +460,19 @@ displayName: existing.displayName }, appName);
         }
 
         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);
         }
 
@@ -487,6 +504,17 @@ displayName: existing.displayName }, appName);
             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");
+            }
+        }
+
         // Apply beforeDelete hook (throw to abort)
         const hookCtx = buildHookContext(c, "DELETE");
         if (hooks?.users?.beforeDelete) {
@@ -513,8 +541,7 @@ displayName: existing.displayName }, appName);
             id: r.id,
             name: r.name,
             isAdmin: r.isAdmin,
-            defaultPermissions: r.defaultPermissions,
-            config: r.config
+            defaultPermissions: r.defaultPermissions
         }));
 
         adminRoles = await applyRoleAfterReadBatch(adminRoles, hookCtx);
@@ -535,7 +562,7 @@ displayName: existing.displayName }, appName);
 
     router.post("/roles", requireAdmin, async (c) => {
         const body = await c.req.json();
-        const { id, name, isAdmin, defaultPermissions, config } = body;
+        const { id, name, isAdmin, defaultPermissions } = body;
 
         if (!id || !name) {
             throw ApiError.badRequest("Role ID and name are required", "INVALID_INPUT");
@@ -550,8 +577,7 @@ displayName: existing.displayName }, appName);
             id,
             name,
             isAdmin: isAdmin ?? false,
-            defaultPermissions: defaultPermissions ?? null,
-            config: config ?? null
+            defaultPermissions: defaultPermissions ?? null
         });
 
         return c.json({ role }, 201);
@@ -560,7 +586,7 @@ displayName: existing.displayName }, appName);
     router.put("/roles/:roleId", requireAdmin, async (c) => {
         const roleId = c.req.param("roleId");
         const body = await c.req.json();
-        const { name, isAdmin, defaultPermissions, config } = body;
+        const { name, isAdmin, defaultPermissions } = body;
 
         const existing = await authRepo.getRoleById(roleId);
         if (!existing) {
@@ -570,8 +596,7 @@ displayName: existing.displayName }, appName);
         const role = await authRepo.updateRole(roleId, {
             name,
             isAdmin,
-            defaultPermissions,
-            config
+            defaultPermissions
         });
 
         return c.json({ role });

package/src/auth/api-keys/api-key-middleware.ts

@@ -0,0 +1,126 @@
+/**
+ * Hono middleware for authenticating requests via Service API Keys.
+ *
+ * This middleware is integrated into `createAuthMiddleware()` and
+ * activates only when the bearer token starts with `rk_`. It:
+ *
+ * 1. Hashes the token with SHA-256
+ * 2. Looks up the hash in the `rebase.api_keys` table
+ * 3. Validates the key is not revoked and not expired
+ * 4. Sets `c.set("user", ...)` and `c.set("apiKey", ...)` for downstream use
+ * 5. Scopes the DataDriver via `withAuth()` using the API key's service identity
+ *
+ * @module
+ */
+
+import { createHash } from "crypto";
+import type { Context } from "hono";
+import type { DataDriver } from "@rebasepro/types";
+import type { HonoEnv } from "../../api/types";
+import type { ApiKeyStore } from "./api-key-store";
+import type { ApiKeyMasked } from "./api-key-types";
+import { scopeDataDriver } from "../rls-scope";
+
+/**
+ * Check whether a token looks like a Rebase API key.
+ */
+export function isApiKeyToken(token: string): boolean {
+    return token.startsWith("rk_");
+}
+
+/**
+ * Hash a plaintext API key token for database lookup.
+ */
+function hashToken(token: string): string {
+    return createHash("sha256").update(token).digest("hex");
+}
+
+/**
+ * Options for the API key authentication handler.
+ */
+export interface ApiKeyAuthOptions {
+    store: ApiKeyStore;
+    driver: DataDriver;
+}
+
+/**
+ * Validate an API key token and populate the Hono context.
+ *
+ * Returns `true` if the key is valid and context has been populated,
+ * or returns an error Response if the key is invalid.
+ *
+ * This is NOT a standalone middleware — it's called from within
+ * `createAuthMiddleware()` when a `rk_` prefixed token is detected.
+ */
+export async function validateApiKey(
+    c: Context<HonoEnv>,
+    token: string,
+    options: ApiKeyAuthOptions,
+): Promise<Response | true> {
+    const { store, driver } = options;
+
+    const hash = hashToken(token);
+    const apiKey = await store.findByKeyHash(hash);
+
+    if (!apiKey) {
+        return c.json({
+            error: { message: "Invalid API key", code: "UNAUTHORIZED" },
+        }, 401);
+    }
+
+    // Check revocation
+    if (apiKey.revoked_at) {
+        return c.json({
+            error: { message: "API key has been revoked", code: "UNAUTHORIZED" },
+        }, 401);
+    }
+
+    // Check expiration
+    if (apiKey.expires_at && new Date(apiKey.expires_at) < new Date()) {
+        return c.json({
+            error: { message: "API key has expired", code: "UNAUTHORIZED" },
+        }, 401);
+    }
+
+    // Set user identity — API keys represent service accounts
+    const userId = `api-key:${apiKey.id}`;
+    c.set("user", { userId, roles: [] });
+
+    // Expose masked key metadata for downstream permission checks
+    const masked: ApiKeyMasked = {
+        id: apiKey.id,
+        name: apiKey.name,
+        key_prefix: apiKey.key_prefix,
+        permissions: apiKey.permissions,
+        rate_limit: apiKey.rate_limit,
+        created_by: apiKey.created_by,
+        created_at: apiKey.created_at,
+        updated_at: apiKey.updated_at,
+        last_used_at: apiKey.last_used_at,
+        expires_at: apiKey.expires_at,
+        revoked_at: apiKey.revoked_at,
+    };
+    // Store apiKey in the context for permission checking in api-generator
+    c.set("apiKey", masked);
+
+    // Scope the DataDriver — API keys bypass RLS (service identity)
+    try {
+        const scopedDriver = await scopeDataDriver(driver, {
+            uid: userId,
+            roles: ["service"],
+        });
+        c.set("driver", scopedDriver);
+    } catch (error) {
+        console.error("[AUTH] RLS scoping failed for API key:", error);
+        return c.json({
+            error: { message: "Internal authentication error", code: "INTERNAL_ERROR" },
+        }, 500);
+    }
+
+    // Touch last_used_at in the background (non-blocking)
+    store.updateLastUsed(apiKey.id).catch(() => {
+        // Swallowed intentionally — logged inside the store
+    });
+
+    return true;
+}

package/src/auth/api-keys/api-key-permission-guard.ts

@@ -0,0 +1,64 @@
+/**
+ * Permission guard for Service API Keys.
+ *
+ * Checks whether an API key's permission set allows a specific operation
+ * on a specific collection. Used by the REST API generator middleware to
+ * enforce fine-grained access control.
+ *
+ * @module
+ */
+
+import type { ApiKeyPermission } from "./api-key-types";
+
+/** Operations that map to HTTP methods. */
+export type ApiKeyOperation = "read" | "write" | "delete";
+
+/**
+ * Map an HTTP method string to an `ApiKeyOperation`.
+ *
+ * - `GET`, `HEAD`, `OPTIONS` → `"read"`
+ * - `POST`, `PUT`, `PATCH`  → `"write"`
+ * - `DELETE`                → `"delete"`
+ */
+export function httpMethodToOperation(method: string): ApiKeyOperation {
+    const upper = method.toUpperCase();
+    switch (upper) {
+        case "GET":
+        case "HEAD":
+        case "OPTIONS":
+            return "read";
+        case "POST":
+        case "PUT":
+        case "PATCH":
+            return "write";
+        case "DELETE":
+            return "delete";
+        default:
+            return "read";
+    }
+}
+
+/**
+ * Check whether the given permissions array allows `operation` on `collection`.
+ *
+ * Supports the `"*"` wildcard for the collection field, which matches any
+ * collection. Returns `true` if at least one permission entry grants access.
+ *
+ * @param permissions - The API key's permission entries.
+ * @param collection  - The target collection slug.
+ * @param operation   - The requested operation.
+ * @returns `true` if the operation is permitted.
+ */
+export function isOperationAllowed(
+    permissions: ApiKeyPermission[],
+    collection: string,
+    operation: ApiKeyOperation,
+): boolean {
+    for (const perm of permissions) {
+        const collectionMatch = perm.collection === "*" || perm.collection === collection;
+        if (collectionMatch && perm.operations.includes(operation)) {
+            return true;
+        }
+    }
+    return false;
+}

package/src/auth/api-keys/api-key-routes.ts

@@ -0,0 +1,183 @@
+/**
+ * Admin routes for managing Service API Keys.
+ *
+ * Mounted under `/api/admin/api-keys` with `requireAuth` + `requireAdmin`.
+ * All routes return masked keys (never the hash). The full plaintext key
+ * is returned exactly once in the POST response.
+ *
+ * @module
+ */
+
+import { Hono } from "hono";
+import { ApiError, errorHandler } from "../../api/errors";
+import { createRequireAuth, requireAdmin } from "../middleware";
+import type { HonoEnv } from "../../api/types";
+import type { ApiKeyStore } from "./api-key-store";
+import type { CreateApiKeyRequest, UpdateApiKeyRequest, ApiKeyPermission } from "./api-key-types";
+
+export interface ApiKeyRouteOptions {
+    store: ApiKeyStore;
+    serviceKey?: string;
+}
+
+/**
+ * Validate that a permissions array is well-formed.
+ */
+function validatePermissions(permissions: unknown): permissions is ApiKeyPermission[] {
+    if (!Array.isArray(permissions)) return false;
+    for (const perm of permissions) {
+        if (typeof perm !== "object" || perm === null) return false;
+        if (typeof perm.collection !== "string" || perm.collection.length === 0) return false;
+        if (!Array.isArray(perm.operations) || perm.operations.length === 0) return false;
+        const validOps = new Set(["read", "write", "delete"]);
+        for (const op of perm.operations) {
+            if (!validOps.has(op)) return false;
+        }
+    }
+    return true;
+}
+
+/**
+ * Create admin routes for API key management.
+ */
+export function createApiKeyRoutes(options: ApiKeyRouteOptions): Hono<HonoEnv> {
+    const { store, serviceKey } = options;
+    const router = new Hono<HonoEnv>();
+
+    router.onError(errorHandler);
+
+    // Apply auth middleware (service-key-aware)
+    router.use("/*", createRequireAuth({ serviceKey }));
+    router.use("/*", requireAdmin);
+
+    // GET / — List all API keys (masked)
+    router.get("/", async (c) => {
+        const keys = await store.listApiKeys();
+        return c.json({ keys });
+    });
+
+    // POST / — Create a new API key
+    router.post("/", async (c) => {
+        const body = await c.req.json() as Record<string, unknown>;
+        const { name, permissions, rate_limit, expires_at } = body;
+
+        if (!name || typeof name !== "string" || name.trim().length === 0) {
+            throw ApiError.badRequest("Name is required", "INVALID_INPUT");
+        }
+
+        if (!validatePermissions(permissions)) {
+            throw ApiError.badRequest(
+                "Permissions must be an array of { collection: string, operations: ('read' | 'write' | 'delete')[] }",
+                "INVALID_INPUT",
+            );
+        }
+
+        if (rate_limit !== undefined && rate_limit !== null) {
+            if (typeof rate_limit !== "number" || rate_limit < 1 || !Number.isInteger(rate_limit)) {
+                throw ApiError.badRequest("rate_limit must be a positive integer or null", "INVALID_INPUT");
+            }
+        }
+
+        if (expires_at !== undefined && expires_at !== null) {
+            const parsed = new Date(expires_at as string);
+            if (isNaN(parsed.getTime())) {
+                throw ApiError.badRequest("expires_at must be a valid ISO-8601 date", "INVALID_INPUT");
+            }
+            if (parsed <= new Date()) {
+                throw ApiError.badRequest("expires_at must be in the future", "INVALID_INPUT");
+            }
+        }
+
+        const user = c.get("user");
+        const createdBy = (user && typeof user === "object" && "userId" in user)
+            ? (user.userId as string)
+            : "unknown";
+
+        const request: CreateApiKeyRequest = {
+            name: name.trim(),
+            permissions: permissions as ApiKeyPermission[],
+            rate_limit: (rate_limit as number | null) ?? null,
+            expires_at: (expires_at as string | null) ?? null,
+        };
+
+        const keyWithSecret = await store.createApiKey(request, createdBy);
+
+        return c.json({ key: keyWithSecret }, 201);
+    });
+
+    // GET /:id — Get API key details (masked)
+    router.get("/:id", async (c) => {
+        const id = c.req.param("id");
+        const key = await store.getApiKeyById(id);
+
+        if (!key) {
+            throw ApiError.notFound("API key not found");
+        }
+
+        return c.json({ key });
+    });
+
+    // PUT /:id — Update API key
+    router.put("/:id", async (c) => {
+        const id = c.req.param("id");
+        const body = await c.req.json() as Record<string, unknown>;
+        const { name, permissions, rate_limit, expires_at } = body;
+
+        // Validate fields if provided
+        if (name !== undefined) {
+            if (typeof name !== "string" || name.trim().length === 0) {
+                throw ApiError.badRequest("Name must be a non-empty string", "INVALID_INPUT");
+            }
+        }
+
+        if (permissions !== undefined) {
+            if (!validatePermissions(permissions)) {
+                throw ApiError.badRequest(
+                    "Permissions must be an array of { collection: string, operations: ('read' | 'write' | 'delete')[] }",
+                    "INVALID_INPUT",
+                );
+            }
+        }
+
+        if (rate_limit !== undefined && rate_limit !== null) {
+            if (typeof rate_limit !== "number" || rate_limit < 1 || !Number.isInteger(rate_limit)) {
+                throw ApiError.badRequest("rate_limit must be a positive integer or null", "INVALID_INPUT");
+            }
+        }
+
+        if (expires_at !== undefined && expires_at !== null) {
+            const parsed = new Date(expires_at as string);
+            if (isNaN(parsed.getTime())) {
+                throw ApiError.badRequest("expires_at must be a valid ISO-8601 date", "INVALID_INPUT");
+            }
+        }
+
+        const updates: UpdateApiKeyRequest = {};
+        if (name !== undefined) updates.name = (name as string).trim();
+        if (permissions !== undefined) updates.permissions = permissions as ApiKeyPermission[];
+        if (rate_limit !== undefined) updates.rate_limit = rate_limit as number | null;
+        if (expires_at !== undefined) updates.expires_at = expires_at as string | null;
+
+        const key = await store.updateApiKey(id, updates);
+
+        if (!key) {
+            throw ApiError.notFound("API key not found");
+        }
+
+        return c.json({ key });
+    });
+
+    // DELETE /:id — Revoke (soft-delete)
+    router.delete("/:id", async (c) => {
+        const id = c.req.param("id");
+        const revoked = await store.revokeApiKey(id);
+
+        if (!revoked) {
+            throw ApiError.notFound("API key not found or already revoked");
+        }
+
+        return c.json({ success: true });
+    });
+
+    return router;
+}