@rebasepro/server-core 0.2.3 → 0.3.0

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

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

@@ -0,0 +1,94 @@
+/**
+ * Type definitions for Service API Keys.
+ *
+ * API keys provide machine-to-machine authentication for scripts, cron jobs,
+ * and third-party integrations. Each key is scoped to specific collections
+ * and operations via the `ApiKeyPermission` model.
+ *
+ * @module
+ */
+
+/**
+ * A single permission entry scoping an API key to a collection and set of operations.
+ *
+ * Use `"*"` as the collection value to grant access to all collections.
+ */
+export interface ApiKeyPermission {
+    /** Collection slug, or `"*"` for all collections. */
+    collection: string;
+    /** Allowed operations on the collection. */
+    operations: ("read" | "write" | "delete")[];
+}
+
+/**
+ * Full database row for an API key.
+ * The `key_hash` is never exposed via the API — only stored for lookup.
+ */
+export interface ApiKey {
+    id: string;
+    name: string;
+    /** First 12 characters of the plaintext key, for display only. */
+    key_prefix: string;
+    /** SHA-256 hash of the full plaintext key. */
+    key_hash: string;
+    permissions: ApiKeyPermission[];
+    /** Requests per 15-minute window. `null` means unlimited. */
+    rate_limit: number | null;
+    created_by: string;
+    created_at: string;
+    updated_at: string;
+    last_used_at: string | null;
+    expires_at: string | null;
+    revoked_at: string | null;
+}
+
+/**
+ * Masked version of an API key, safe for API responses.
+ * Omits `key_hash` and shows only the prefix.
+ */
+export interface ApiKeyMasked {
+    id: string;
+    name: string;
+    key_prefix: string;
+    permissions: ApiKeyPermission[];
+    rate_limit: number | null;
+    created_by: string;
+    created_at: string;
+    updated_at: string;
+    last_used_at: string | null;
+    expires_at: string | null;
+    revoked_at: string | null;
+}
+
+/**
+ * Request body for creating a new API key.
+ */
+export interface CreateApiKeyRequest {
+    name: string;
+    permissions: ApiKeyPermission[];
+    /** Requests per 15-minute window. Omit or `null` for unlimited. */
+    rate_limit?: number | null;
+    /** ISO-8601 expiration timestamp. Omit for no expiration. */
+    expires_at?: string | null;
+}
+
+/**
+ * Request body for updating an existing API key.
+ * All fields are optional — only provided fields are updated.
+ */
+export interface UpdateApiKeyRequest {
+    name?: string;
+    permissions?: ApiKeyPermission[];
+    rate_limit?: number | null;
+    expires_at?: string | null;
+}
+
+/**
+ * Returned exactly once when a key is created.
+ * The `key` field contains the full plaintext key — it is never stored
+ * or returned again after creation.
+ */
+export interface ApiKeyWithSecret extends ApiKeyMasked {
+    /** Full plaintext API key (e.g. `rk_live_abc123...`). */
+    key: string;
+}

package/src/auth/api-keys/index.ts

@@ -0,0 +1,37 @@
+/**
+ * Service API Keys module.
+ *
+ * Re-exports types, store, middleware, permission guard, and routes
+ * for the API key authentication system.
+ *
+ * @module
+ */
+
+// Types
+export type {
+    ApiKey,
+    ApiKeyMasked,
+    ApiKeyPermission,
+    ApiKeyWithSecret,
+    CreateApiKeyRequest,
+    UpdateApiKeyRequest,
+} from "./api-key-types";
+
+// Store
+export { createApiKeyStore } from "./api-key-store";
+export type { ApiKeyStore } from "./api-key-store";
+
+// Middleware
+export { isApiKeyToken, validateApiKey } from "./api-key-middleware";
+export type { ApiKeyAuthOptions } from "./api-key-middleware";
+
+// Permission guard
+export {
+    httpMethodToOperation,
+    isOperationAllowed,
+} from "./api-key-permission-guard";
+export type { ApiKeyOperation } from "./api-key-permission-guard";
+
+// Routes
+export { createApiKeyRoutes } from "./api-key-routes";
+export type { ApiKeyRouteOptions } from "./api-key-routes";

package/src/auth/{auth-overrides.ts → auth-hooks.ts}

@@ -1,20 +1,20 @@
 /**
- * AuthOverrides
+ * AuthHooks
  *
- * Override specific behaviors of the built-in Rebase auth system.
+ * Customize specific behaviors of the built-in Rebase auth system.
  *
  * Each method replaces one piece of the default implementation.
  * Unset methods fall through to the built-in defaults (scrypt passwords,
  * standard validation rules, etc.).
  *
- * This interface is intentionally open for extension — new overrides
+ * This interface is intentionally open for extension — new hooks
  * can be added as optional methods without breaking existing configurations.
  *
  * @example bcrypt password support
  * ```ts
  * import bcrypt from "bcrypt";
  *
- * const overrides: AuthOverrides = {
+ * const hooks: AuthHooks = {
  *     hashPassword: (pw) => bcrypt.hash(pw, 12),
  *     verifyPassword: (pw, hash) => bcrypt.compare(pw, hash),
  *     validatePasswordStrength: (pw) => ({
@@ -26,7 +26,7 @@
  *
  * @example Override the entire login credential check
  * ```ts
- * const overrides: AuthOverrides = {
+ * const hooks: AuthHooks = {
  *     verifyCredentials: async (email, password, repo) => {
  *         const user = await repo.getUserByEmail(email);
  *         if (!user || !user.passwordHash) return null;
@@ -48,15 +48,15 @@ import type { AuthRepository, UserData, CreateUserData } from "./interfaces";
 /**
  * Authentication method identifier for lifecycle hooks.
  */
-export type AuthMethod = "login" | "register" | "oauth" | "refresh" | "password-reset";
+export type AuthMethod = "login" | "register" | "oauth" | "refresh" | "password-reset" | "anonymous" | "magic-link" | "mfa";
 
 /**
- * Override specific parts of the built-in Rebase auth implementation.
+ * Hook specific parts of the built-in Rebase auth implementation.
  *
  * Every method is optional. The built-in defaults apply for any method
  * that is not provided.
  */
-export interface AuthOverrides {
+export interface AuthHooks {
     // ─── Password Operations ──────────────────────────────────────────────
 
     /**
@@ -138,11 +138,78 @@ export interface AuthOverrides {
      * This is fire-and-forget — errors are logged but do not fail the request.
      */
     afterUserCreate?(user: UserData): Promise<void>;
+
+    // ─── Extended Lifecycle Hooks ─────────────────────────────────────────
+
+    /**
+     * Pre-login validation. Called before credential verification.
+     *
+     * Throw an error to reject the login attempt (e.g. for account lockout,
+     * IP-based restrictions, etc.).
+     */
+    beforeLogin?(email: string, method: AuthMethod): Promise<void>;
+
+    /**
+     * Post-logout cleanup.
+     *
+     * Called after a user's session has been invalidated.
+     * Use for audit logging, cleanup of temporary resources, etc.
+     *
+     * This is fire-and-forget — errors are logged but do not fail the request.
+     */
+    afterLogout?(userId: string): Promise<void>;
+
+    /**
+     * Called after successful MFA verification.
+     *
+     * Use for audit logging, notifying external systems, etc.
+     *
+     * This is fire-and-forget — errors are logged but do not fail the request.
+     */
+    onMfaVerified?(userId: string, factorId: string): Promise<void>;
+
+    /**
+     * Customize JWT access token claims before signing.
+     *
+     * Return the modified claims object. The returned claims are merged
+     * into the JWT payload alongside standard claims (userId, roles).
+     *
+     * @param claims - The default claims that would be included.
+     * @param user - The authenticated user data.
+     * @returns Modified claims to include in the JWT.
+     */
+    customizeAccessToken?(claims: Record<string, unknown>, user: UserData): Promise<Record<string, unknown>>;
+
+    /**
+     * Called after a successful password reset.
+     *
+     * Use for audit logging, sending confirmation notifications, etc.
+     *
+     * This is fire-and-forget — errors are logged but do not fail the request.
+     */
+    onPasswordReset?(userId: string): Promise<void>;
+
+    /**
+     * Called before a user is deleted.
+     *
+     * Throw an error to prevent deletion (e.g. for users with active
+     * subscriptions, pending transactions, etc.).
+     */
+    beforeUserDelete?(userId: string): Promise<void>;
+
+    /**
+     * Called after a user is deleted.
+     *
+     * Use for cleaning up external resources, audit logging, etc.
+     *
+     * This is fire-and-forget — errors are logged but do not fail the request.
+     */
+    afterUserDelete?(userId: string): Promise<void>;
 }
 
 /**
  * Resolved auth operations — every method is guaranteed to exist.
- * Created by `resolveAuthOverrides()` which merges user overrides
+ * Created by `resolveAuthHooks()` which merges user hooks
  * with built-in defaults.
  */
 export interface ResolvedAuthOperations {
@@ -152,21 +219,21 @@ export interface ResolvedAuthOperations {
 }
 
 /**
- * Merge user-provided overrides with the built-in defaults to produce
+ * Merge user-provided hooks with the built-in defaults to produce
  * a complete set of resolved operations.
  *
  * This is the single point where defaults are applied — all consumers
  * call this once and use the resolved operations throughout.
  */
-export function resolveAuthOverrides(overrides?: AuthOverrides): ResolvedAuthOperations {
+export function resolveAuthHooks(hooks?: AuthHooks): ResolvedAuthOperations {
     return {
-        hashPassword: overrides?.hashPassword
+        hashPassword: hooks?.hashPassword
             ?? defaultHashPassword,
 
-        verifyPassword: overrides?.verifyPassword
+        verifyPassword: hooks?.verifyPassword
             ?? defaultVerifyPassword,
 
-        validatePasswordStrength: overrides?.validatePasswordStrength
+        validatePasswordStrength: hooks?.validatePasswordStrength
             ?? defaultValidatePasswordStrength,
     };
 }