@rebasepro/server-core 0.2.3 → 0.2.5

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;
+}

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

@@ -0,0 +1,317 @@
+/**
+ * Database operations for Service API Keys.
+ *
+ * Uses the DataDriver's `admin.executeSql` capability (same pattern as
+ * the cron-store and ensure-tables modules). All data lives in the
+ * `rebase.api_keys` table.
+ *
+ * @module
+ */
+
+import { randomBytes, createHash } from "crypto";
+import type { DataDriver } from "@rebasepro/types";
+import { isSQLAdmin } from "@rebasepro/types";
+import { logger } from "../../utils/logger";
+import type {
+    ApiKey,
+    ApiKeyMasked,
+    ApiKeyWithSecret,
+    CreateApiKeyRequest,
+    UpdateApiKeyRequest,
+} from "./api-key-types";
+
+const TABLE = "rebase.api_keys";
+
+/** Characters used to generate the random portion of an API key. */
+const HEX_CHARS = "abcdef0123456789";
+
+/**
+ * Generate a plaintext API key with the `rk_live_` prefix.
+ *
+ * Format: `rk_live_` + 32 random hex characters.
+ */
+function generateApiKey(): string {
+    const random = randomBytes(16).toString("hex"); // 32 hex chars
+    return `rk_live_${random}`;
+}
+
+/**
+ * SHA-256 hash a plaintext API key for database storage.
+ */
+function hashKey(plaintext: string): string {
+    return createHash("sha256").update(plaintext).digest("hex");
+}
+
+/**
+ * Extract the display prefix from a plaintext key (first 12 chars).
+ */
+function keyPrefix(plaintext: string): string {
+    return plaintext.substring(0, 12);
+}
+
+/**
+ * Strip the `key_hash` field and return a safe-to-expose masked key.
+ */
+function toMasked(row: ApiKey): ApiKeyMasked {
+    return {
+        id: row.id,
+        name: row.name,
+        key_prefix: row.key_prefix,
+        permissions: row.permissions,
+        rate_limit: row.rate_limit,
+        created_by: row.created_by,
+        created_at: row.created_at,
+        updated_at: row.updated_at,
+        last_used_at: row.last_used_at,
+        expires_at: row.expires_at,
+        revoked_at: row.revoked_at,
+    };
+}
+
+/**
+ * Parse a raw DB row into the typed `ApiKey` shape.
+ */
+function rowToApiKey(row: Record<string, unknown>): ApiKey {
+    const permissions = typeof row.permissions === "string"
+        ? JSON.parse(row.permissions)
+        : (row.permissions ?? []);
+
+    return {
+        id: row.id as string,
+        name: row.name as string,
+        key_prefix: row.key_prefix as string,
+        key_hash: row.key_hash as string,
+        permissions,
+        rate_limit: row.rate_limit !== null && row.rate_limit !== undefined
+            ? Number(row.rate_limit)
+            : null,
+        created_by: row.created_by as string,
+        created_at: new Date(row.created_at as string).toISOString(),
+        updated_at: new Date(row.updated_at as string).toISOString(),
+        last_used_at: row.last_used_at ? new Date(row.last_used_at as string).toISOString() : null,
+        expires_at: row.expires_at ? new Date(row.expires_at as string).toISOString() : null,
+        revoked_at: row.revoked_at ? new Date(row.revoked_at as string).toISOString() : null,
+    };
+}
+
+/**
+ * Escape a string for safe inline SQL usage.
+ */
+function esc(value: string): string {
+    return value.replace(/'/g, "''");
+}
+
+// ─── Public API ──────────────────────────────────────────────────────
+
+export interface ApiKeyStore {
+    /** Ensure the `rebase.api_keys` table exists. Called once on startup. */
+    ensureTable(): Promise<void>;
+
+    /** Create a new API key. Returns the full plaintext key exactly once. */
+    createApiKey(request: CreateApiKeyRequest, createdBy: string): Promise<ApiKeyWithSecret>;
+
+    /** Look up an API key by its SHA-256 hash. Returns `null` if not found. */
+    findByKeyHash(hash: string): Promise<ApiKey | null>;
+
+    /** List all API keys (masked, never includes hash). */
+    listApiKeys(): Promise<ApiKeyMasked[]>;
+
+    /** Get a single API key by ID (masked). */
+    getApiKeyById(id: string): Promise<ApiKeyMasked | null>;
+
+    /** Update name, permissions, rate_limit, or expires_at. */
+    updateApiKey(id: string, updates: UpdateApiKeyRequest): Promise<ApiKeyMasked | null>;
+
+    /** Soft-delete: set `revoked_at` to now. */
+    revokeApiKey(id: string): Promise<boolean>;
+
+    /** Touch `last_used_at` to the current timestamp. */
+    updateLastUsed(id: string): Promise<void>;
+}
+
+/**
+ * Create an `ApiKeyStore` backed by the driver's SQL admin capability.
+ *
+ * Returns `undefined` if the driver does not support `executeSql`.
+ */
+export function createApiKeyStore(driver: DataDriver): ApiKeyStore | undefined {
+    const admin = driver.admin;
+    if (!isSQLAdmin(admin)) {
+        logger.warn("⚠️ [api-key-store] DataDriver does not support SQL admin — API keys will not be available.");
+        return undefined;
+    }
+
+    const exec = admin.executeSql.bind(admin);
+
+    return {
+        // ── Schema bootstrap ────────────────────────────────────────
+        async ensureTable(): Promise<void> {
+            try {
+                await exec("CREATE SCHEMA IF NOT EXISTS rebase");
+                await exec(`
+                    CREATE TABLE IF NOT EXISTS ${TABLE} (
+                        id TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
+                        name TEXT NOT NULL,
+                        key_prefix TEXT NOT NULL,
+                        key_hash TEXT NOT NULL UNIQUE,
+                        permissions JSONB NOT NULL DEFAULT '[]'::jsonb,
+                        rate_limit INTEGER,
+                        created_by TEXT NOT NULL,
+                        created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                        updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                        last_used_at TIMESTAMPTZ,
+                        expires_at TIMESTAMPTZ,
+                        revoked_at TIMESTAMPTZ
+                    )
+                `);
+
+                await exec(`
+                    CREATE INDEX IF NOT EXISTS idx_api_keys_hash
+                    ON ${TABLE}(key_hash)
+                `);
+
+                await exec(`
+                    CREATE INDEX IF NOT EXISTS idx_api_keys_prefix
+                    ON ${TABLE}(key_prefix)
+                `);
+
+                logger.info("✅ API keys table ready");
+            } catch (err) {
+                logger.error("❌ Failed to create API keys table", { error: err });
+                logger.warn("⚠️ Continuing without API keys support.");
+            }
+        },
+
+        // ── Create ──────────────────────────────────────────────────
+        async createApiKey(request: CreateApiKeyRequest, createdBy: string): Promise<ApiKeyWithSecret> {
+            const plaintext = generateApiKey();
+            const hash = hashKey(plaintext);
+            const prefix = keyPrefix(plaintext);
+            const permissionsJson = JSON.stringify(request.permissions);
+            const rateLimitSql = request.rate_limit !== null && request.rate_limit !== undefined
+                ? String(request.rate_limit)
+                : "NULL";
+            const expiresAtSql = request.expires_at
+                ? `'${esc(request.expires_at)}'`
+                : "NULL";
+
+            const rows = await exec(`
+                INSERT INTO ${TABLE} (name, key_prefix, key_hash, permissions, rate_limit, created_by, expires_at)
+                VALUES (
+                    '${esc(request.name)}',
+                    '${esc(prefix)}',
+                    '${esc(hash)}',
+                    '${esc(permissionsJson)}'::jsonb,
+                    ${rateLimitSql},
+                    '${esc(createdBy)}',
+                    ${expiresAtSql}
+                )
+                RETURNING *
+            `);
+
+            const apiKey = rowToApiKey(rows[0]);
+            return {
+                ...toMasked(apiKey),
+                key: plaintext,
+            };
+        },
+
+        // ── Lookup by hash ──────────────────────────────────────────
+        async findByKeyHash(hash: string): Promise<ApiKey | null> {
+            const rows = await exec(`
+                SELECT * FROM ${TABLE}
+                WHERE key_hash = '${esc(hash)}'
+                LIMIT 1
+            `);
+            if (rows.length === 0) return null;
+            return rowToApiKey(rows[0]);
+        },
+
+        // ── List all (masked) ───────────────────────────────────────
+        async listApiKeys(): Promise<ApiKeyMasked[]> {
+            const rows = await exec(`
+                SELECT * FROM ${TABLE}
+                ORDER BY created_at DESC
+            `);
+            return rows.map(r => toMasked(rowToApiKey(r)));
+        },
+
+        // ── Get by ID (masked) ──────────────────────────────────────
+        async getApiKeyById(id: string): Promise<ApiKeyMasked | null> {
+            const rows = await exec(`
+                SELECT * FROM ${TABLE}
+                WHERE id = '${esc(id)}'
+                LIMIT 1
+            `);
+            if (rows.length === 0) return null;
+            return toMasked(rowToApiKey(rows[0]));
+        },
+
+        // ── Update ──────────────────────────────────────────────────
+        async updateApiKey(id: string, updates: UpdateApiKeyRequest): Promise<ApiKeyMasked | null> {
+            const setClauses: string[] = [];
+
+            if (updates.name !== undefined) {
+                setClauses.push(`name = '${esc(updates.name)}'`);
+            }
+            if (updates.permissions !== undefined) {
+                setClauses.push(`permissions = '${esc(JSON.stringify(updates.permissions))}'::jsonb`);
+            }
+            if (updates.rate_limit !== undefined) {
+                setClauses.push(
+                    updates.rate_limit !== null
+                        ? `rate_limit = ${updates.rate_limit}`
+                        : "rate_limit = NULL"
+                );
+            }
+            if (updates.expires_at !== undefined) {
+                setClauses.push(
+                    updates.expires_at !== null
+                        ? `expires_at = '${esc(updates.expires_at)}'`
+                        : "expires_at = NULL"
+                );
+            }
+
+            if (setClauses.length === 0) {
+                return this.getApiKeyById(id);
+            }
+
+            setClauses.push("updated_at = NOW()");
+
+            const rows = await exec(`
+                UPDATE ${TABLE}
+                SET ${setClauses.join(", ")}
+                WHERE id = '${esc(id)}'
+                RETURNING *
+            `);
+
+            if (rows.length === 0) return null;
+            return toMasked(rowToApiKey(rows[0]));
+        },
+
+        // ── Revoke (soft-delete) ────────────────────────────────────
+        async revokeApiKey(id: string): Promise<boolean> {
+            const rows = await exec(`
+                UPDATE ${TABLE}
+                SET revoked_at = NOW(), updated_at = NOW()
+                WHERE id = '${esc(id)}' AND revoked_at IS NULL
+                RETURNING id
+            `);
+            return rows.length > 0;
+        },
+
+        // ── Touch last_used_at ──────────────────────────────────────
+        async updateLastUsed(id: string): Promise<void> {
+            try {
+                await exec(`
+                    UPDATE ${TABLE}
+                    SET last_used_at = NOW()
+                    WHERE id = '${esc(id)}'
+                `);
+            } catch (err) {
+                // Non-blocking — don't fail requests because of a usage timestamp update
+                logger.error("[api-key-store] Failed to update last_used_at", { error: err });
+            }
+        },
+    };
+}